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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atomadic-forge
-Version: 0.53.0
+Version: 0.54.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
@@ -136,6 +136,8 @@ Forge enforces a **5-tier monadic law** — every source file belongs to exactly
 |---------|-------------|
 | `forge smell` | Code smell scan: cyclomatic complexity, long functions, duplicates |
 | `forge call-graph` | AST call graph for any symbol |
+| `forge call-graph-summary` | Whole-package call-graph portfolio — orphans, fan-in hotspots, max depth |
+| `forge churn` | File-level git commit frequency — hotspot and stable files |
 | `forge cna-check` | Compose-Not-Add — flag duplicates before writing |
 | `forge trust-gate` | LLM response hallucination detector |
 | `forge preflight` | Pre-edit guardrail: tier + import + scope check |
@@ -158,7 +160,7 @@ 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 |
 
-**26+ CLI verbs total.** Full reference: [docs/02-commands.md](docs/02-commands.md)
+**74 CLI verbs total.** Full reference: [docs/02-commands.md](docs/02-commands.md)
 
 ---
 
@@ -177,12 +179,12 @@ Forge ships a Model Context Protocol server. Add it to Cursor, Claude Code, Aide
 }
 ```
 
-**10 tools, 65 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, 66 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` | 9 | Analyze, understand, discover — recon/explain/call_graph/smell/lineage/harvest/synergy/scan/swarm |
+| `explore` | 11 | Analyze, understand, discover — recon/explain/call_graph/call_graph_summary/smell/lineage/harvest/synergy/scan/swarm/churn |
 | `audit` | 14 | 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 |
@@ -204,10 +206,10 @@ Full tool reference: [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) | First call: `welco
 
 | Metric | Value |
 |--------|-------|
-| MCP tools | **10 tools · 64 actions** |
-| CLI verbs | **71** |
+| MCP tools | **10 tools · 66 actions** |
+| CLI verbs | **74** |
 | Source files | **211** (~40,195 LOC) |
-| Tests | **1,495 passing** across **97 test files** (1,411 static · pytest expands parametrize to 1,495 collected) |
+| Tests | **1,423 passing** across **97 test files** |
 | Lean4 formal proofs | **872 theorems** across 30 files (mathematically verified core logic — IP-protected formal verification moat) |
 | Monadic tiers | **5** (a0 → a4, strict upward-only composition) |
 | Languages | Python, JS/TS, Swift, Kotlin, Go, Rust |
@@ -225,7 +227,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 5 tools (64 actions), 5k calls/mo, signed receipts, custom recipes |
+| **Starter** | $79/mo | All 10 tools (66 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.53.0 → atomadic_forge-0.54.0}/README.md

@@ -104,6 +104,8 @@ Forge enforces a **5-tier monadic law** — every source file belongs to exactly
 |---------|-------------|
 | `forge smell` | Code smell scan: cyclomatic complexity, long functions, duplicates |
 | `forge call-graph` | AST call graph for any symbol |
+| `forge call-graph-summary` | Whole-package call-graph portfolio — orphans, fan-in hotspots, max depth |
+| `forge churn` | File-level git commit frequency — hotspot and stable files |
 | `forge cna-check` | Compose-Not-Add — flag duplicates before writing |
 | `forge trust-gate` | LLM response hallucination detector |
 | `forge preflight` | Pre-edit guardrail: tier + import + scope check |
@@ -126,7 +128,7 @@ 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 |
 
-**26+ CLI verbs total.** Full reference: [docs/02-commands.md](docs/02-commands.md)
+**74 CLI verbs total.** Full reference: [docs/02-commands.md](docs/02-commands.md)
 
 ---
 
@@ -145,12 +147,12 @@ Forge ships a Model Context Protocol server. Add it to Cursor, Claude Code, Aide
 }
 ```
 
-**10 tools, 65 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, 66 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` | 9 | Analyze, understand, discover — recon/explain/call_graph/smell/lineage/harvest/synergy/scan/swarm |
+| `explore` | 11 | Analyze, understand, discover — recon/explain/call_graph/call_graph_summary/smell/lineage/harvest/synergy/scan/swarm/churn |
 | `audit` | 14 | 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 |
@@ -172,10 +174,10 @@ Full tool reference: [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) | First call: `welco
 
 | Metric | Value |
 |--------|-------|
-| MCP tools | **10 tools · 64 actions** |
-| CLI verbs | **71** |
+| MCP tools | **10 tools · 66 actions** |
+| CLI verbs | **74** |
 | Source files | **211** (~40,195 LOC) |
-| Tests | **1,495 passing** across **97 test files** (1,411 static · pytest expands parametrize to 1,495 collected) |
+| Tests | **1,423 passing** across **97 test files** |
 | Lean4 formal proofs | **872 theorems** across 30 files (mathematically verified core logic — IP-protected formal verification moat) |
 | Monadic tiers | **5** (a0 → a4, strict upward-only composition) |
 | Languages | Python, JS/TS, Swift, Kotlin, Go, Rust |
@@ -193,7 +195,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 5 tools (64 actions), 5k calls/mo, signed receipts, custom recipes |
+| **Starter** | $79/mo | All 10 tools (66 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.53.0 → atomadic_forge-0.54.0}/docs/AGENTS_GUIDE.md

@@ -326,6 +326,8 @@ agent tool-selection can route by trigger phrase. Quick reference:
 | An LLM response needs hallucination checking | `trust_gate_response` |
 | A module's docstring promises need verification | `verify {check_exports: true}` (folds `exported_api_check`) |
 | You want to find what a target symbol calls or is called by | `call_graph` |
+| You want a whole-package call-graph portfolio (orphans, hotspots, max depth) | `call_graph_summary` — `explore(action='call_graph_summary')` |
+| You want file-level git commit frequency (churn hotspots and stable files) | `churn` — `explore(action='churn')` |
 | You want to flag complexity / long-function / duplicate-body code smells | `smell_scan` |
 | You want to recall what prior agents learned about this repo | `wisdom recall` (or read `prior_wisdom` from `recon`) |
 | You want to record a lesson for future agents | `wisdom record` |
@@ -357,6 +359,8 @@ agent tool-selection can route by trigger phrase. Quick reference:
 | `sidecar_validate` |  | `trust_gate_response` |  |
 | `manifest_diff` |  | `cna_check` (compose-not-add gate) |  |
 | `call_graph` (callers/callees) |  | `smell_scan` (CC / LOC / dup) |  |
+| `call_graph_summary` (portfolio: orphans/hotspots) |  |  |  |
+| `churn` (git commit frequency by file) |  |  |  |
 | `wisdom_record` / `wisdom_query` / `wisdom_list` / `wisdom_recall` / `wisdom_promote` (since v0.13.1–v0.13.3) |  | `guard_install` (4-layer immune system) |  |
 | `surface` (emit / check / diff) |  |  |  |
 | `nexus_identity_verify` / `nexus_federation_mint` / `nexus_authorize_action` / `nexus_sys_trust_gate` / `nexus_contract_verify` / `nexus_lineage_record` / `nexus_ratchet_register` (since v0.14.0a7) |  |  |  |
@@ -379,6 +383,8 @@ in a loop:
 | **`sidecar_validate`** | sidecar drift findings (S0000–S0007) | After authoring or editing a `.forge` sidecar file. |
 | **`manifest_diff`** | added / removed / changed entries between two manifests | After a `commandsmith` sync or between two `certify` runs to track trajectory. |
 | **`call_graph`** | callers / callees up to `max_depth` hops (BFS, AST-based) | Before mutating a target symbol; closes Forge's call-graph gap vs Code Pathfinder / Moderne. |
+| **`call_graph_summary`** (`explore(action='call_graph_summary')`) | whole-package call-graph portfolio: `orphans` (unreachable symbols), `hotspots` ranked by fan-in, `max_depth`; schema `atomadic-forge.call_graph_summary/v1` | When you need a portfolio view of the entire package's call topology — which symbols are islands, which are load-bearing. CLI: `forge call-graph-summary --project <root> [--package NAME] [--top-n N] [--json]`. |
+| **`churn`** (`explore(action='churn')`) | file-level git commit frequency: `hotspot_files`, `stable_files`, `avg_commits`, `median_commits`, `date_range`; schema `atomadic-forge.git_churn/v1` | When you want to know which files change most often (high review priority) and which are stable (safe to refactor). CLI: `forge churn --project <root> [--since '6 months ago'] [--top-n N] [--all-files] [--json]`. |
 | **`smell_scan`** | cyclomatic-complexity / long-function / duplicate-body findings + `smell_score` | When `certify` is green but maintainability is still suspect. |
 | **`wisdom_record` / `wisdom_query` / `wisdom_list` / `wisdom_recall`** (since v0.13.1) | append entry / relevance-rank / full DB read / top-N repo-scoped recall against `.atomadic-forge/wisdom.jsonl` | Agents inherit prior lessons (`wisdom_recall`); record new ones after accepted fixes (`wisdom_record`). The 4-tool MCP surface that lets Cognition wire `WISDOM_RECORD` as a cycle action verb. |
 | **`surface`** | emit / check / diff the canonical `surface.json` artifact | CI gate (`check`) and consumer bootstrap (`emit`); zero hand-maintained tool maps. |
@@ -397,7 +403,7 @@ always-on senior engineer beside the coding agent:
 
 | Tool | Schema | Call when |
 |---|---|---|
-| **`context_pack`** ← *Codex-4* | `context_pack/v1` — repo purpose, pinned 5-tier law, tier_map, blockers digest, best-next-action, detected test commands, release gate, risky files, recent lineage, pinned `forge://` resources, **`prior_wisdom`** | **First call after `initialize`** — orientation bundle. One round-trip replaces 6+ separate calls. |
+| **`context_pack`** ← *Codex-4* | `context_pack/v1` — repo purpose, pinned 5-tier law, tier_map, blockers digest, best-next-action, detected test commands, release gate, risky files, recent lineage, pinned `forge://` resources, **`prior_wisdom`**, **`token_estimate`** (payload byte length ÷ 4) | **First call after `initialize`** — orientation bundle. One round-trip replaces 6+ separate calls. Use `token_estimate` to size the payload before inserting into a context window. |
 | **`doctor` (with `include_worktree: true`)** | `doctor/v1` + worktree fields — git root, branch, upstream drift, dirty files, remotes, version surfaces, resolved `forge` command, stale-command detection, recommendations (folds the retired `worktree_status`) | **Before editing or release work** when there are multiple checkouts, stale MCP concerns, dirty trees, or version mismatches. |
 | **`preflight_change`** ← *Codex-4* | `preflight/v1` — per file: detected_tier, forbidden_imports, likely_tests, siblings_to_read; overall write_scope_too_broad flag | **Before** every `WriteFile` / `Edit`. Verdict `REFINE` when scope > 8 files. |
 | **`score_patch`** ← *Codex-4* | `patch_score/v1` — architectural_risk, public_api_risk, release_risk, test_risk, `needs_human_review`, suggested validation commands | **After** drafting a unified-diff but **before** applying. |

{atomadic_forge-0.53.0 → atomadic_forge-0.54.0}/docs/COMMANDS.md

@@ -1,6 +1,6 @@
 # Atomadic Forge — Command Reference
 
-All verbs available in the `forge` CLI as of 0.14.0a10.
+All verbs available in the `forge` CLI as of 0.53.0.
 
 > For the structured per-verb reference (with options, examples, and
 > output samples), see [02-commands.md](02-commands.md). This page is
@@ -494,7 +494,7 @@ Prints the installed Forge version and exits 0. Hardened in v0.3.0
 
 ```bash
 $ forge --version
-atomadic-forge 0.14.0a10
+atomadic-forge 0.53.0
 ```
 
 ### `.forge` sidecars — Lane D W8
@@ -788,6 +788,26 @@ Auto-register, document, and smoke-test every CLI command. Use after
 
 Environment diagnostic — version, Python, encoding, executable.
 
+### `forge call-graph-summary`
+
+Whole-package call-graph portfolio using pyan synthesis. Returns orphans (symbols with no callers), hotspots ranked by fan-in, and maximum call depth across the package.
+
+```bash
+forge call-graph-summary --project <root> [--package NAME] [--top-n N] [--json]
+```
+
+Schema: `atomadic-forge.call_graph_summary/v1`. MCP: `explore(action='call_graph_summary')`. a1 source: `a1_at_functions/call_graph.py` → `build_call_graph_summary()`.
+
+### `forge churn`
+
+File-level git commit frequency via Repomix synthesis. Returns `hotspot_files`, `stable_files`, `avg_commits`, `median_commits`, and the date range analyzed.
+
+```bash
+forge churn --project <root> [--since '6 months ago'] [--top-n N] [--all-files] [--json]
+```
+
+Schema: `atomadic-forge.git_churn/v1`. MCP: `explore(action='churn')`. a1 source: `a1_at_functions/git_churn.py` → `compute_git_churn()`.
+
 ## LLM provider matrix
 
 | Provider | Cost | Env var | Default model | Notes |

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "atomadic-forge"
-version = "0.53.0"
+version = "0.54.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.54.0/src/atomadic_forge/a1_at_functions/capability_scout.py

@@ -0,0 +1,142 @@
+"""Tier a1 — capability scout: search GitHub for harvest-worthy repositories.
+
+Bridges the gap between "I want a capability" and "here are repos to harvest."
+Uses the GitHub Search API (no auth needed for basic search) plus heuristic
+ranking on stars, freshness, and Python relevance.
+
+Pure: no writes.  HTTP via urllib stdlib only.  Returns a graceful error dict
+if the network is unavailable.
+"""
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+SCHEMA_VERSION_CAPABILITY_SCOUT_V1 = "atomadic-forge.capability_scout/v1"
+
+_GITHUB_SEARCH = "https://api.github.com/search/repositories"
+_USER_AGENT = "atomadic-forge-capability-scout/0.1"
+_RATE_DELAY = 1.2  # seconds between GitHub API calls (unauthenticated: 10/min)
+
+
+def _gh_search(query: str, per_page: int = 10) -> list[dict]:
+    params = urllib.parse.urlencode({
+        "q": query,
+        "sort": "stars",
+        "order": "desc",
+        "per_page": per_page,
+    })
+    url = f"{_GITHUB_SEARCH}?{params}"
+    req = urllib.request.Request(url, headers={"User-Agent": _USER_AGENT,
+                                                "Accept": "application/vnd.github.v3+json"})
+    try:
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            data = json.loads(resp.read().decode())
+            return data.get("items", [])
+    except (urllib.error.URLError, urllib.error.HTTPError, OSError, json.JSONDecodeError):
+        return []
+
+
+def _score_item(item: dict, query: str) -> float:
+    """Heuristic harvest-confidence score 0-100."""
+    stars = item.get("stargazers_count", 0)
+    lang = (item.get("language") or "").lower()
+    description = (item.get("description") or "").lower()
+    name = item.get("full_name", "").lower()
+    topics = [t.lower() for t in item.get("topics", [])]
+    pushed = item.get("pushed_at", "")
+
+    score = 0.0
+
+    # Stars: log scale, cap at 50 pts
+    if stars > 0:
+        import math
+        score += min(math.log10(stars + 1) * 15, 50)
+
+    # Python preference (forge is Python-first)
+    if lang == "python":
+        score += 20
+    elif lang in ("rust", "typescript", "javascript"):
+        score += 5
+
+    # Query keyword match in name/description/topics
+    query_words = set(query.lower().split())
+    desc_words = set(description.split())
+    name_words = set(name.replace("-", " ").replace("_", " ").split("/")[-1].split())
+    topic_words = set(t for topic in topics for t in topic.split("-"))
+    overlap = query_words & (desc_words | name_words | topic_words)
+    score += len(overlap) * 4
+
+    # Freshness: pushed within last 180 days
+    if pushed:
+        try:
+            from datetime import datetime, timezone
+            pushed_dt = datetime.fromisoformat(pushed.replace("Z", "+00:00"))
+            days_old = (datetime.now(timezone.utc) - pushed_dt).days
+            if days_old < 180:
+                score += max(0, 10 - days_old // 18)
+        except (ValueError, TypeError):
+            pass
+
+    return min(round(score, 1), 100.0)
+
+
+def scout_capabilities(
+    queries: list[str],
+    *,
+    per_query: int = 8,
+    min_score: float = 30.0,
+    dedupe: bool = True,
+) -> dict[str, Any]:
+    """Search GitHub for repos matching capability queries.
+
+    Args:
+        queries: List of search queries (e.g. ["dead code detection python"]).
+        per_query: Max results per query (GitHub cap: 30 without auth).
+        min_score: Minimum harvest-confidence score to include.
+        dedupe: Skip repos already seen from a previous query.
+
+    Returns structured dict with ``schema_version``, ``targets`` (ranked),
+    ``query_count``, ``total_found``.  Degrades gracefully on network error.
+    """
+    seen_ids: set[int] = set()
+    all_targets: list[dict] = []
+
+    for i, query in enumerate(queries):
+        if i > 0:
+            time.sleep(_RATE_DELAY)
+        items = _gh_search(f"{query} language:python", per_page=per_query)
+        for item in items:
+            rid = item.get("id", 0)
+            if dedupe and rid in seen_ids:
+                continue
+            seen_ids.add(rid)
+            score = _score_item(item, query)
+            if score < min_score:
+                continue
+            all_targets.append({
+                "repo": item.get("full_name", ""),
+                "url": item.get("html_url", ""),
+                "clone_url": item.get("clone_url", ""),
+                "stars": item.get("stargazers_count", 0),
+                "language": item.get("language", ""),
+                "description": (item.get("description") or "")[:200],
+                "topics": item.get("topics", [])[:8],
+                "pushed_at": item.get("pushed_at", ""),
+                "harvest_score": score,
+                "matched_query": query,
+            })
+
+    # Sort by score desc
+    all_targets.sort(key=lambda x: -x["harvest_score"])
+
+    return {
+        "schema_version": SCHEMA_VERSION_CAPABILITY_SCOUT_V1,
+        "query_count": len(queries),
+        "total_candidates": len(all_targets),
+        "targets": all_targets,
+    }

atomadic_forge-0.54.0/src/atomadic_forge/a1_at_functions/dead_code_check.py

@@ -0,0 +1,160 @@
+"""Tier a1 — dead code checker: find defined-but-unreferenced symbols.
+
+Synthesised from vulture (jendrikseipp/vulture) — MIT license.
+Uses pure AST analysis to find names that are defined but never imported,
+called, or accessed in the scanned package.  No dynamic analysis required.
+
+Pure: read-only AST walks, no subprocess, no writes.  Degrades gracefully
+on syntax errors by reporting the offending file and skipping it.
+"""
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import Any
+
+SCHEMA_VERSION_DEAD_CODE_V1 = "atomadic-forge.dead_code/v1"
+
+
+def _collect_definitions(tree: ast.AST, module: str) -> dict[str, str]:
+    """Collect all top-level name definitions: {qualname: kind}."""
+    defs: dict[str, str] = {}
+    for node in ast.walk(tree):
+        if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+            defs[f"{module}.{node.name}"] = "function"
+        elif isinstance(node, ast.ClassDef):
+            defs[f"{module}.{node.name}"] = "class"
+        elif isinstance(node, ast.Assign):
+            for target in node.targets:
+                if isinstance(target, ast.Name) and not target.id.startswith("_"):
+                    defs[f"{module}.{target.id}"] = "variable"
+        elif isinstance(node, ast.ImportFrom):
+            for alias in node.names:
+                name = alias.asname or alias.name
+                if not name.startswith("_"):
+                    defs[f"{module}.{name}"] = "import"
+    return defs
+
+
+def _collect_usages(tree: ast.AST) -> set[str]:
+    """Collect all name tokens used (called, accessed, passed) in a module."""
+    usages: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Name):
+            usages.add(node.id)
+        elif isinstance(node, ast.Attribute):
+            usages.add(node.attr)
+        elif isinstance(node, ast.Call):
+            if isinstance(node.func, ast.Name):
+                usages.add(node.func.id)
+            elif isinstance(node.func, ast.Attribute):
+                usages.add(node.func.attr)
+    return usages
+
+
+def check_dead_code(
+    project_root: Path,
+    *,
+    package: str | None = None,
+    include_imports: bool = False,
+    include_variables: bool = False,
+    confidence_threshold: float = 60.0,
+) -> dict[str, Any]:
+    """Find defined-but-unreferenced symbols across a Python package.
+
+    Args:
+        project_root: Repository root.
+        package: Package subdirectory to scan. Auto-detected if None.
+        include_imports: Include unused imports in results (noisy).
+        include_variables: Include unused module-level variables.
+        confidence_threshold: Minimum confidence to report (60–100).
+
+    Returns dict with ``schema_version``, ``dead_symbols``, counts, and
+    per-module breakdowns.  ``confidence`` is higher when a symbol is
+    never referenced in ANY file in the package (100) vs. only some (60–80).
+    """
+    root = Path(project_root).resolve()
+
+    # Locate package
+    src = root / "src"
+    if package:
+        pkg_dir = (src / package) if src.is_dir() else (root / package)
+    else:
+        pkg_dir = None
+        for candidate in ([src] if src.is_dir() else [root]):
+            for sub in sorted(candidate.iterdir()):
+                if sub.is_dir() and (sub / "__init__.py").exists():
+                    pkg_dir = sub
+                    break
+            if pkg_dir:
+                break
+    if pkg_dir is None or not pkg_dir.is_dir():
+        return {
+            "schema_version": SCHEMA_VERSION_DEAD_CODE_V1,
+            "available": False,
+            "reason": "package directory not found",
+        }
+
+    py_files = sorted(pkg_dir.rglob("*.py"))
+    trees: list[tuple[str, ast.AST]] = []
+    parse_errors: list[str] = []
+
+    for py in py_files:
+        rel = py.relative_to(pkg_dir)
+        module = ".".join(rel.with_suffix("").parts).replace(".__init__", "")
+        try:
+            tree = ast.parse(py.read_text(encoding="utf-8", errors="replace"))
+            trees.append((module, tree))
+        except SyntaxError as e:
+            parse_errors.append(f"{py}: {e}")
+
+    # Gather all definitions
+    all_defs: dict[str, str] = {}
+    for module, tree in trees:
+        all_defs.update(_collect_definitions(tree, module))
+
+    # Gather all usages (unqualified names) across the whole package
+    all_usages: set[str] = set()
+    for _, tree in trees:
+        all_usages.update(_collect_usages(tree))
+
+    dead_symbols: list[dict] = []
+    for qualname, kind in sorted(all_defs.items()):
+        if kind == "import" and not include_imports:
+            continue
+        if kind == "variable" and not include_variables:
+            continue
+        # Extract the bare name (last segment)
+        bare_name = qualname.rsplit(".", 1)[-1]
+        if bare_name.startswith("_"):
+            continue
+        # __dunder__ methods are always used implicitly
+        if bare_name.startswith("__") and bare_name.endswith("__"):
+            continue
+        if bare_name in all_usages:
+            continue
+        # Not found in any usage — dead
+        confidence = 80 if kind in ("function", "class") else 60
+        if confidence < confidence_threshold:
+            continue
+        module = qualname.rsplit(".", 1)[0] if "." in qualname else qualname
+        dead_symbols.append({
+            "qualname": qualname,
+            "kind": kind,
+            "confidence": confidence,
+            "module": module,
+        })
+
+    return {
+        "schema_version": SCHEMA_VERSION_DEAD_CODE_V1,
+        "available": True,
+        "package": pkg_dir.name,
+        "files_scanned": len(trees),
+        "parse_errors": parse_errors,
+        "dead_symbol_count": len(dead_symbols),
+        "dead_symbols": dead_symbols,
+        "dead_by_kind": {
+            k: sum(1 for s in dead_symbols if s["kind"] == k)
+            for k in ("function", "class", "variable", "import")
+        },
+    }