atomadic-forge 0.52.1__tar.gz → 0.53.0__tar.gz

{atomadic_forge-0.52.1 → atomadic_forge-0.53.0}/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 ## Unreleased
 
+## v0.53.0 — 2026-05-07 — Harvest synthesis: call-graph-summary, git churn, token budget
+
+### feat(synthesis): three new a1 capabilities absorbed from harvest pipeline
+
+**`call_graph_summary` — whole-package call-graph portfolio** (pyan synthesis)
+
+Adds `build_call_graph_summary()` to `a1_at_functions/call_graph.py`.
+Surfaces orphan functions (uncalled callers), hotspot functions by fan-in,
+and maximum call-chain depth for an entire package in one shot — distinct from
+the per-symbol BFS that `call_graph` already provides.
+
+- `forge call-graph-summary --project <root> [--package NAME] [--top-n N] [--json]`
+- MCP: `explore(action='call_graph_summary')`
+- Schema: `atomadic-forge.call_graph_summary/v1`
+
+**`git_churn` — file-level commit frequency** (Repomix synthesis)
+
+New `a1_at_functions/git_churn.py` with `compute_git_churn()`.
+Runs `git log --name-only` to build hotspot/stable file rankings, average and
+median commits per file, first/last commit dates. Returns a minimal error dict
+when git is unavailable so callers degrade gracefully.
+
+- `forge churn --project <root> [--since '6 months ago'] [--top-n N] [--all-files] [--json]`
+- MCP: `explore(action='churn')`
+- Schema: `atomadic-forge.git_churn/v1`
+
+**`token_estimate` — context-pack payload sizing** (Repomix synthesis)
+
+`emit_context_pack()` now includes `token_estimate: int` — a `len(json.dumps(pack)) // 4`
+approximation so agents can budget against context limits before dispatching.
+
+### metrics
+
+- CLI verbs: 74 (+2)
+- MCP actions: 66 (+2)
+- Tests: 1423 (+14 over v0.52.1)
+
 ## v0.52.1 — 2026-05-07 — IP scrub: no private identifiers in public repo
 
 ### fix(security): remove all private identifiers from public surfaces

{atomadic_forge-0.52.1/src/atomadic_forge.egg-info → atomadic_forge-0.53.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atomadic-forge
-Version: 0.52.1
+Version: 0.53.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

{atomadic_forge-0.52.1 → atomadic_forge-0.53.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "atomadic-forge"
-version = "0.52.1"
+version = "0.53.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.52.1 → atomadic_forge-0.53.0}/src/atomadic_forge/a1_at_functions/agent_context_pack.py

@@ -13,6 +13,7 @@ single bundle. The orchestration that runs the scans lives in a3.
 """
 from __future__ import annotations
 
+import json
 import re
 from collections import Counter
 from pathlib import Path
@@ -136,6 +137,7 @@ class ContextPack(TypedDict, total=False):
     selected_tests: dict
     workflow_recipe: dict          # compose_tools plan when intent is provided
     suggested_next_steps: list[dict]
+    token_estimate: int            # rough token count (chars // 4); repomix synthesis
 
 
 def _read_repo_purpose(project_root: Path) -> str:
@@ -442,7 +444,7 @@ def emit_context_pack(
             project_root=project_root,
         )
 
-    return ContextPack(
+    pack = ContextPack(
         schema_version=SCHEMA_VERSION_CONTEXT_PACK_V1,
         project_root=str(project_root),
         repo_purpose=_read_repo_purpose(project_root),
@@ -478,4 +480,12 @@ def emit_context_pack(
             release_gate=release_gate,
             selected_tests=selected_tests,
         ),
+        token_estimate=0,
     )
+    # Patch token_estimate after build — rough approximation: JSON chars / 4 ≈ tokens.
+    # No external tokenizer required; accurate enough for context budget decisions.
+    try:
+        pack["token_estimate"] = len(json.dumps(pack, default=str)) // 4
+    except (TypeError, ValueError):
+        pass
+    return pack

{atomadic_forge-0.52.1 → atomadic_forge-0.53.0}/src/atomadic_forge/a1_at_functions/call_graph.py

@@ -419,3 +419,113 @@ def build_call_graph(args: dict[str, Any]) -> dict[str, Any]:
         "callees_count": len(callees),
         "target_in_graph": canonical_target in edges,
     }
+
+
+# ── Whole-package summary (pyan synthesis) ────────────────────────────
+
+SCHEMA_VERSION_CALL_GRAPH_SUMMARY_V1 = "atomadic-forge.call_graph_summary/v1"
+
+
+def _compute_fan_in(edges: dict[str, set[str]]) -> dict[str, int]:
+    fan_in: dict[str, int] = defaultdict(int)
+    for callees in edges.values():
+        for callee in callees:
+            fan_in[callee] += 1
+    return dict(fan_in)
+
+
+def _max_chain_depth(
+    edges: dict[str, set[str]],
+    starts: list[str],
+    *,
+    cap: int = 15,
+) -> int:
+    """BFS from each start node; return the longest path found (capped)."""
+    best = 0
+    for start in starts[:100]:
+        visited: set[str] = {start}
+        queue: deque[tuple[str, int]] = deque([(start, 0)])
+        while queue:
+            node, d = queue.popleft()
+            if d >= cap:
+                continue
+            for callee in edges.get(node, ()):
+                if callee not in visited:
+                    visited.add(callee)
+                    if d + 1 > best:
+                        best = d + 1
+                    queue.append((callee, d + 1))
+    return best
+
+
+def build_call_graph_summary(args: dict[str, Any]) -> dict[str, Any]:
+    """Whole-package call-graph portfolio: orphans, hotspots, max depth.
+
+    Synthesized from pyan (David Fraser) whole-graph analysis concepts.
+    Unlike ``build_call_graph`` (per-symbol callers/callees), this gives
+    a portfolio view of the entire package's call structure — useful for
+    dead-code audits, refactor prioritization, and complexity estimation.
+
+    Args (from the dispatcher):
+      * ``project_root`` (default: cwd): repo root.
+      * ``package`` (default: derived): top-level package name.
+      * ``top_n`` (default 10): number of hotspot/orphan rows to return.
+    """
+    project_root = Path(args.get("project_root") or ".").resolve()
+    top_n = min(int(args.get("top_n", 10)), 50)
+
+    _raw_package = args.get("package") or _detect_package_name(project_root)
+    package = _raw_package.replace("-", "_")
+
+    package_root = project_root / "src" / package
+    if not package_root.exists():
+        candidate = project_root / package
+        package_root = candidate if candidate.exists() else project_root
+
+    edges = _walk_package_edges(package_root, package=package)
+    aliases = _build_reexport_aliases(package_root, package=package)
+
+    if aliases:
+        canonical_edges: dict[str, set[str]] = defaultdict(set)
+        for caller, callees_set in edges.items():
+            canonical_caller = _canonicalize(caller, aliases)
+            for callee in callees_set:
+                canonical_edges[canonical_caller].add(
+                    _canonicalize(callee, aliases)
+                )
+        edges = dict(canonical_edges)
+
+    fan_in = _compute_fan_in(edges)
+
+    # Defined = every function that appears as a caller (has ≥1 outgoing edge).
+    defined: set[str] = {f for f in edges if f.startswith(package)}
+    called: set[str] = {f for f in fan_in if f.startswith(package)}
+
+    # Uncalled callers: defined but never called from within the package.
+    # These may be entry-points (CLI/MCP handlers) or dead code.
+    uncalled = sorted(defined - called)
+
+    # Hotspots: package functions with the highest internal fan-in.
+    hotspots = sorted(
+        [{"qualname": q, "fan_in": c} for q, c in fan_in.items()
+         if q.startswith(package)],
+        key=lambda x: -x["fan_in"],
+    )[:top_n]
+
+    max_depth = _max_chain_depth(edges, uncalled)
+
+    total_edges = sum(len(v) for v in edges.values())
+
+    return {
+        "schema_version": SCHEMA_VERSION_CALL_GRAPH_SUMMARY_V1,
+        "package": package,
+        "package_root": str(package_root),
+        "total_callers": len(defined),
+        "total_edges": total_edges,
+        "uncalled_callers_count": len(uncalled),
+        "uncalled_callers": uncalled[:top_n],
+        "hotspot_count": len(hotspots),
+        "hotspots": hotspots,
+        "max_call_depth": max_depth,
+        "alias_count": len(aliases),
+    }

atomadic_forge-0.53.0/src/atomadic_forge/a1_at_functions/git_churn.py

@@ -0,0 +1,129 @@
+"""Tier a1 — git churn analysis: file-level commit frequency from git log.
+
+Synthesized from Repomix's ``calculateGitLogMetrics`` concept.  Forge's
+recon already captures static structure (symbol counts, complexity).
+Git churn adds a **temporal quality axis**: which files change most
+often, how recently, and how stable the codebase is over time.
+
+Pure in the Forge sense: read-only subprocess calls to ``git log``,
+no writes, no state mutation.  Returns ``None`` if the repo has no git
+history or git is unavailable — callers degrade gracefully.
+"""
+from __future__ import annotations
+
+import subprocess
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+SCHEMA_VERSION_GIT_CHURN_V1 = "atomadic-forge.git_churn/v1"
+
+_GIT_TIMEOUT = 10  # seconds
+
+
+def _run_git(args: list[str], cwd: Path) -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", *args],
+            cwd=str(cwd),
+            capture_output=True,
+            text=True,
+            timeout=_GIT_TIMEOUT,
+        )
+        return result.stdout if result.returncode == 0 else None
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        return None
+
+
+def _commit_count_per_file(repo_root: Path, *, since: str = "") -> dict[str, int]:
+    """Return {relative_path: commit_count} for every tracked file."""
+    args = ["log", "--name-only", "--pretty=format:"]
+    if since:
+        args += ["--since", since]
+    out = _run_git(args, repo_root)
+    if out is None:
+        return {}
+    counts: dict[str, int] = defaultdict(int)
+    for line in out.splitlines():
+        line = line.strip()
+        if line:
+            counts[line] += 1
+    return dict(counts)
+
+
+def _first_and_last_commit_date(repo_root: Path) -> tuple[str, str]:
+    first = _run_git(["log", "--reverse", "--pretty=format:%ci", "--diff-filter=A", "--", "."], repo_root)
+    last = _run_git(["log", "-1", "--pretty=format:%ci"], repo_root)
+    first_date = (first or "").splitlines()[0][:10] if first else ""
+    last_date = (last or "").strip()[:10] if last else ""
+    return first_date, last_date
+
+
+def _total_commits(repo_root: Path) -> int:
+    out = _run_git(["rev-list", "--count", "HEAD"], repo_root)
+    try:
+        return int((out or "0").strip())
+    except ValueError:
+        return 0
+
+
+def compute_git_churn(
+    project_root: Path,
+    *,
+    top_n: int = 15,
+    since: str = "",
+    src_only: bool = True,
+) -> dict[str, Any]:
+    """Compute file-level git churn metrics for a repository.
+
+    Args:
+        project_root: repository root.
+        top_n: number of highest-churn files to surface.
+        since: optional git date filter (e.g. ``"6 months ago"``).
+        src_only: when True, restrict results to files under ``src/``.
+
+    Returns a structured dict with ``schema_version``, ``hotspot_files``,
+    ``stable_files``, ``total_commits``, ``churn_period``, plus aggregate
+    stats.  Returns a minimal error dict if git is unavailable.
+    """
+    root = Path(project_root).resolve()
+    counts = _commit_count_per_file(root, since=since)
+    if not counts:
+        return {
+            "schema_version": SCHEMA_VERSION_GIT_CHURN_V1,
+            "available": False,
+            "reason": "no git history or git not available",
+        }
+
+    if src_only:
+        counts = {p: c for p, c in counts.items() if p.startswith("src/")}
+
+    total = _total_commits(root)
+    first_date, last_date = _first_and_last_commit_date(root)
+
+    sorted_files = sorted(counts.items(), key=lambda x: -x[1])
+    hotspots = [
+        {"path": p, "commits": c} for p, c in sorted_files[:top_n]
+    ]
+    stable = [
+        {"path": p, "commits": c}
+        for p, c in sorted_files[::-1][:top_n]
+        if c <= 2
+    ]
+
+    avg_churn = sum(counts.values()) / len(counts) if counts else 0.0
+    median_churn = sorted(counts.values())[len(counts) // 2] if counts else 0
+
+    return {
+        "schema_version": SCHEMA_VERSION_GIT_CHURN_V1,
+        "available": True,
+        "total_commits": total,
+        "files_tracked": len(counts),
+        "churn_period": since or "all time",
+        "first_commit_date": first_date,
+        "last_commit_date": last_date,
+        "avg_commits_per_file": round(avg_churn, 2),
+        "median_commits_per_file": median_churn,
+        "hotspot_files": hotspots,
+        "stable_files": stable[:top_n],
+    }

{atomadic_forge-0.52.1 → atomadic_forge-0.53.0}/src/atomadic_forge/a1_at_functions/mcp_protocol.py

@@ -19,7 +19,7 @@ consume on first connect:
 
 Tools (v0.47.0 — 8 tools, 64 actions + create):
   welcome  — first-call handshake (no action param)
-  explore  — codebase analysis + discovery (action=recon|explain|call_graph|smell_scan|lineage|harvest|synergy|scan|swarm)
+  explore  — codebase analysis + discovery (action=recon|explain|call_graph|call_graph_summary|smell_scan|churn|lineage|harvest|synergy|scan|swarm)
   audit    — quality gates + change safety (action=certify|wire|enforce|validate|guard|composite|gate|health|check|score|tests|cna|rollback|diff)
   plan     — orient + plan + execute (action=context|compose|policy|recipes|generate|apply|locate|commit|iterate|resume|evolve|evolve_step|auto|cherry|finalize|scaffold)
   hive     — multi-agent coordination (action=register|list|deactivate|observe|propose|vote|needs_vote|result|recap|handoff_create|handoff_list|enhance_propose|enhance_list)
@@ -1131,6 +1131,29 @@ def _tool_call_graph(project_root: Path, args: dict[str, Any]) -> dict[str, Any]
     return build_call_graph(merged_args)
 
 
+def _tool_call_graph_summary(project_root: Path, args: dict[str, Any]) -> dict[str, Any]:
+    """Whole-package call-graph portfolio: orphans, hotspots, max depth.
+    Synthesised from pyan whole-graph analysis concepts."""
+    from .call_graph import build_call_graph_summary
+    merged_args = dict(args)
+    if "project_root" not in merged_args:
+        merged_args["project_root"] = str(project_root)
+    return build_call_graph_summary(merged_args)
+
+
+def _tool_git_churn(project_root: Path, args: dict[str, Any]) -> dict[str, Any]:
+    """File-level git churn metrics: hotspot files, stable files, commit
+    frequency distribution. Synthesised from Repomix git-log concepts."""
+    from .git_churn import compute_git_churn
+    root = Path(args.get("project_root", project_root)).resolve()
+    return compute_git_churn(
+        root,
+        top_n=int(args.get("top_n", 15)),
+        since=str(args.get("since", "")),
+        src_only=bool(args.get("src_only", True)),
+    )
+
+
 def _tool_smell_scan(project_root: Path, args: dict[str, Any]) -> dict[str, Any]:
     """Run code-smell detection (cyclomatic complexity + long functions
     + duplicated bodies). Pure: composes the a1 ``smell_scan`` walker."""
@@ -2016,14 +2039,17 @@ def _tool_plan_merged(project_root: Path, args: dict[str, Any]) -> dict[str, Any
 
 
 def _tool_code_intel(project_root: Path, args: dict[str, Any]) -> dict[str, Any]:
-    """Merged code intelligence: call_graph/smell_scan."""
+    """Merged code intelligence: call_graph/call_graph_summary/smell_scan."""
     action = str(args.get("action", ""))
     inner = {k: v for k, v in args.items() if k != "action"}
     if action == "call_graph":
         return _tool_call_graph(project_root, inner)
+    elif action == "call_graph_summary":
+        return _tool_call_graph_summary(project_root, inner)
     elif action == "smell_scan":
         return _tool_smell_scan(project_root, inner)
-    return {"error": f"Unknown action {action!r}", "valid_actions": ["call_graph", "smell_scan"]}
+    return {"error": f"Unknown action {action!r}",
+            "valid_actions": ["call_graph", "call_graph_summary", "smell_scan"]}
 
 
 def _tool_preflight_merged(project_root: Path, args: dict[str, Any]) -> dict[str, Any]:
@@ -2121,7 +2147,7 @@ def _tool_discover(project_root: Path, args: dict[str, Any]) -> dict[str, Any]:
 
 def _tool_explore(project_root: Path, args: dict[str, Any]) -> dict[str, Any]:
     """Merged exploration + discovery:
-    recon/explain/call_graph/smell_scan/lineage/harvest/synergy/scan/swarm."""
+    recon/explain/call_graph/call_graph_summary/smell_scan/churn/lineage/harvest/synergy/scan/swarm."""
     action = str(args.get("action", "recon"))
     inner = {k: v for k, v in args.items() if k != "action"}
     if action == "recon":
@@ -2132,8 +2158,12 @@ def _tool_explore(project_root: Path, args: dict[str, Any]) -> dict[str, Any]:
         return _tool_explain_repo(project_root, inner)
     elif action == "call_graph":
         return _tool_call_graph(project_root, inner)
+    elif action == "call_graph_summary":
+        return _tool_call_graph_summary(project_root, inner)
     elif action == "smell_scan":
         return _tool_smell_scan(project_root, inner)
+    elif action == "churn":
+        return _tool_git_churn(project_root, inner)
     elif action == "lineage":
         return _tool_lineage(project_root, inner)
     # discover actions
@@ -2147,7 +2177,8 @@ def _tool_explore(project_root: Path, args: dict[str, Any]) -> dict[str, Any]:
         inner["action"] = action
         return _tool_emergent(project_root, inner)
     return {"error": f"Unknown action {action!r}",
-            "valid_actions": ["recon", "explain", "call_graph", "smell_scan", "lineage",
+            "valid_actions": ["recon", "explain", "call_graph", "call_graph_summary",
+                              "smell_scan", "churn", "lineage",
                               "harvest", "synergy", "scan", "swarm"]}
 
 
@@ -2363,7 +2394,9 @@ TOOLS: dict[str, dict[str, Any]] = {
             "action='recon' (default): maps every public symbol into the 5 monadic tiers. "
             "action='explain': plain-English orientation — one-liner, core flow, do_not_break. "
             "action='call_graph': AST BFS walk — callers/callees of a target symbol. "
+            "action='call_graph_summary': whole-package portfolio — orphans, hotspots, max depth. "
             "action='smell_scan': CC monsters, long functions, dup bodies (smell_score 0-100). "
+            "action='churn': file-level git churn — hotspot/stable files, avg/median commits. "
             "action='lineage': query the .atomadic-forge lineage log (mode=all/by_file/failed_for_area). "
             "action='harvest': cross-repo cherry-hunter — diffs target vs source repos, "
             "ranks graft candidates by trust-gated confidence (max-depth 23, no LLM). "
@@ -2377,12 +2410,14 @@ TOOLS: dict[str, dict[str, Any]] = {
             "properties": {
                 "action": {
                     "type": "string",
-                    "enum": ["recon", "explain", "call_graph", "smell_scan", "lineage",
+                    "enum": ["recon", "explain", "call_graph", "call_graph_summary",
+                             "smell_scan", "churn", "lineage",
                              "harvest", "synergy", "scan", "swarm"],
                     "default": "recon",
                     "description": (
                         "'recon' — tier map; 'explain' — narrative; "
-                        "'call_graph' — symbol graph; 'smell_scan' — code smell; "
+                        "'call_graph' — symbol graph; 'call_graph_summary' — package portfolio; "
+                        "'smell_scan' — code smell; 'churn' — git file churn; "
                         "'lineage' — audit log; 'harvest' — cross-repo grafts; "
                         "'synergy' — composition patterns; "
                         "'scan' — single-repo emergent; 'swarm' — multi-repo emergent."
@@ -2419,6 +2454,11 @@ TOOLS: dict[str, dict[str, Any]] = {
                                     "description": "[smell_scan] Optional subdir under project_root."},
                 "top_n_findings": {"type": "integer", "default": 20,
                                     "description": "[smell_scan] Cap findings per category (0=unlimited)."},
+                # churn params
+                "since": {"type": "string", "default": "",
+                           "description": "[churn] Git date filter (e.g. '6 months ago'). Empty = all time."},
+                "src_only": {"type": "boolean", "default": True,
+                              "description": "[churn/call_graph_summary] Restrict to src/ files only."},
                 # lineage params
                 "mode": {"type": "string", "enum": ["all", "by_file", "failed_for_area"],
                           "default": "all", "description": "[lineage] Query mode."},
@@ -3121,6 +3161,8 @@ _CLI_FALLBACKS: dict[str, str] = {
         "forge recon <repo> --json (action=recon) | "
         "forge explain-repo <project-root> (action=explain) | "
         "forge call-graph <qualname> --project-root <repo> --json (action=call_graph) | "
+        "forge call-graph-summary --project <repo> --json (action=call_graph_summary) | "
+        "forge churn --project <repo> --json (action=churn) | "
         "forge smell-scan --project-root <repo> --json (action=smell_scan) | "
         "forge surface list/show/log (action=lineage)"
     ),
@@ -3201,6 +3243,8 @@ _CLI_FALLBACKS: dict[str, str] = {
     ),
     "code_intel": (
         "forge call-graph <qualname> --project-root <repo> --json — use explore(action=call_graph) via MCP | "
+        "forge call-graph-summary --project <repo> --json — use explore(action=call_graph_summary) via MCP | "
+        "forge churn --project <repo> --json — use explore(action=churn) via MCP | "
         "forge smell-scan --project-root <repo> --json — use explore(action=smell_scan) via MCP"
     ),
     "forge_util": (

{atomadic_forge-0.52.1 → atomadic_forge-0.53.0}/src/atomadic_forge/a4_sy_orchestration/cli.py

@@ -1217,6 +1217,85 @@ def call_graph_cmd(
         typer.echo("  (no edges found — check that qualname and package are correct)")
 
 
+@app.command("call-graph-summary")
+def call_graph_summary_cmd(
+    project_root: Annotated[Path, typer.Option(
+        "--project",
+        exists=True, file_okay=False, dir_okay=True, resolve_path=True,
+        help="Project root.")] = Path("."),
+    package: Annotated[str | None, typer.Option(
+        "--package", help="Python package name.")] = None,
+    top_n: Annotated[int, typer.Option(
+        "--top-n", help="Max hotspots / orphans to surface.")] = 10,
+    json_out: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Whole-package call-graph portfolio: orphans, hotspots, max depth."""
+    from ..a1_at_functions.call_graph import build_call_graph_summary
+    report = build_call_graph_summary({
+        "project_root": str(project_root),
+        "package": package,
+        "top_n": top_n,
+    })
+    if json_out:
+        typer.echo(json.dumps(report, indent=2, default=str))
+        return
+    typer.echo(f"\nForge call-graph-summary: {project_root}")
+    typer.echo("-" * 60)
+    typer.echo(f"  package:          {report.get('package', '?')}")
+    typer.echo(f"  total_callers:    {report.get('total_callers', '?')}")
+    typer.echo(f"  total_edges:      {report.get('total_edges', '?')}")
+    typer.echo(f"  max_call_depth:   {report.get('max_call_depth', '?')}")
+    typer.echo(f"  uncalled_callers: {report.get('uncalled_callers_count', '?')}")
+    hotspots = report.get("hotspots", [])
+    if hotspots:
+        typer.echo(f"  hotspots (top {len(hotspots)}):")
+        for h in hotspots:
+            typer.echo(f"    [{h.get('fan_in', 0):>3} calls in] {h.get('qualname', '?')}")
+
+
+@app.command("churn")
+def churn_cmd(
+    project_root: Annotated[Path, typer.Option(
+        "--project",
+        exists=True, file_okay=False, dir_okay=True, resolve_path=True,
+        help="Project root (must be a git repo).")] = Path("."),
+    since: Annotated[str, typer.Option(
+        "--since", help="Git date filter, e.g. '6 months ago'.")] = "",
+    top_n: Annotated[int, typer.Option(
+        "--top-n", help="Hotspot / stable files to surface.")] = 15,
+    all_files: Annotated[bool, typer.Option(
+        "--all-files", help="Include all files, not just src/.")] = False,
+    json_out: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Git churn analysis — which files change most / least often."""
+    from ..a1_at_functions.git_churn import compute_git_churn
+    report = compute_git_churn(
+        project_root, top_n=top_n, since=since, src_only=not all_files
+    )
+    if json_out:
+        typer.echo(json.dumps(report, indent=2, default=str))
+        return
+    if not report.get("available"):
+        typer.echo(f"Git churn unavailable: {report.get('reason', 'unknown')}")
+        return
+    typer.echo(f"\nForge churn: {project_root}")
+    typer.echo("-" * 60)
+    typer.echo(f"  period:           {report['churn_period']}")
+    typer.echo(f"  total_commits:    {report['total_commits']}")
+    typer.echo(f"  files_tracked:    {report['files_tracked']}")
+    typer.echo(f"  avg commits/file: {report['avg_commits_per_file']}")
+    hotspots = report.get("hotspot_files", [])
+    if hotspots:
+        typer.echo(f"  hotspot files (top {len(hotspots)}):")
+        for h in hotspots:
+            typer.echo(f"    [{h['commits']:>4}] {h['path']}")
+    stable = report.get("stable_files", [])
+    if stable:
+        typer.echo(f"  stable files (≤2 commits, top {len(stable)}):")
+        for s in stable:
+            typer.echo(f"    [{s['commits']:>4}] {s['path']}")
+
+
 @app.command("cna-check")
 def cna_check_cmd(
     proposed_name: Annotated[str, typer.Argument(

{atomadic_forge-0.52.1 → atomadic_forge-0.53.0/src/atomadic_forge.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atomadic-forge
-Version: 0.52.1
+Version: 0.53.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

{atomadic_forge-0.52.1 → atomadic_forge-0.53.0}/src/atomadic_forge.egg-info/SOURCES.txt

@@ -173,6 +173,7 @@ src/atomadic_forge/a1_at_functions/forge_feedback.py
 src/atomadic_forge/a1_at_functions/forge_locate.py
 src/atomadic_forge/a1_at_functions/forge_metrics.py
 src/atomadic_forge/a1_at_functions/generation_quality.py
+src/atomadic_forge/a1_at_functions/git_churn.py
 src/atomadic_forge/a1_at_functions/handoff_builder.py
 src/atomadic_forge/a1_at_functions/harvest_absorb.py
 src/atomadic_forge/a1_at_functions/hive_consensus_math.py
@@ -329,6 +330,7 @@ tests/test_agent_plan_pkg_label.py
 tests/test_agent_summary.py
 tests/test_audit_verb.py
 tests/test_body_extractor_repairs.py
+tests/test_call_graph_summary.py
 tests/test_card_renderer.py
 tests/test_certify_operational_axis.py
 tests/test_chat.py
@@ -362,6 +364,7 @@ tests/test_forge_auth_a1.py
 tests/test_forge_auth_a2.py
 tests/test_forge_enforce.py
 tests/test_generation_quality.py
+tests/test_git_churn.py
 tests/test_handoff.py
 tests/test_hierarchical_memory.py
 tests/test_hive_sync.py