roam-code 12.2.0__tar.gz → 12.3.1__tar.gz

{roam_code-12.2.0/src/roam_code.egg-info → roam_code-12.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roam-code
-Version: 12.2.0
+Version: 12.3.1
 Summary: Instant codebase comprehension for AI coding agents
 Author: CosmoHac
 License-Expression: MIT
@@ -29,7 +29,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: click>=8.0
 Requires-Dist: tree-sitter>=0.23
-Requires-Dist: tree-sitter-language-pack>=0.6
+Requires-Dist: tree-sitter-language-pack<1.6.3,>=0.6
 Requires-Dist: networkx>=3.0
 Provides-Extra: mcp
 Requires-Dist: fastmcp>=2.0; extra == "mcp"
@@ -49,6 +49,8 @@ Requires-Dist: lightgbm>=4.0; extra == "learned"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-xdist>=3.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: scipy>=1.11; extra == "dev"
 Requires-Dist: ruff>=0.4; extra == "dev"
 Requires-Dist: build>=1.0; extra == "dev"
 Requires-Dist: twine>=5.0; extra == "dev"

{roam_code-12.2.0 → roam_code-12.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "roam-code"
-version = "12.2.0"
+version = "12.3.1"
 description = "Instant codebase comprehension for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -32,7 +32,11 @@ classifiers = [
 dependencies = [
     "click>=8.0",
     "tree-sitter>=0.23",
-    "tree-sitter-language-pack>=0.6",
+    # Pinned upper bound: 1.6.3's cp312 wheel ships a manylinux_2_34
+    # tarball that fails to register the ``tree_sitter_language_pack``
+    # module post-install (CI run 25217131296). 1.6.2 (cp310-abi3) works
+    # cleanly across 3.9–3.13.
+    "tree-sitter-language-pack>=0.6,<1.6.3",
     "networkx>=3.0",
 ]
 
@@ -81,6 +85,16 @@ learned = [
 dev = [
     "pytest>=7.0",
     "pytest-xdist>=3.0",
+    # pytest-asyncio is required by tests/test_taint_classifier.py — those
+    # tests use ``@pytest.mark.asyncio`` to verify the MCP-sampling-based
+    # taint classifier under a controlled async loop.
+    "pytest-asyncio>=0.23",
+    # scipy is required by ``nx.pagerank`` on networkx 3.x; without it,
+    # the personalized-pagerank tests exercise the degree-based fallback
+    # which doesn't honour ``alpha`` and trivially fails the
+    # alpha-override / chain-propagation invariants. Production users
+    # without scipy still get the (less accurate but correct) fallback.
+    "scipy>=1.11",
     "ruff>=0.4",
     "build>=1.0",
     "twine>=5.0",
@@ -92,10 +106,17 @@ where = ["src"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 addopts = "-q --tb=short"
+# v12.2: pytest-asyncio strict-mode + auto fixture loop scope. Avoids the
+# 11 PytestUnknownMarkWarning warnings on `@pytest.mark.asyncio` in
+# test_taint_classifier.py when pytest-asyncio is installed (it ships
+# under the `[dev]` extra).
+asyncio_mode = "strict"
+asyncio_default_fixture_loop_scope = "function"
 markers = [
     "smoke: fast, high-signal tests for local iteration",
     "core: broader local suite for pre-push checks",
     "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "asyncio: marks async tests requiring pytest-asyncio (skip when missing)",
 ]
 
 [tool.ruff]

{roam_code-12.2.0 → roam_code-12.3.1}/src/roam/commands/cmd_critique.py

@@ -31,6 +31,57 @@ from roam.critique.checks import (
 from roam.db.connection import open_db
 from roam.output.formatter import json_envelope, to_json
 
+# Hot-path → bench command. When a diff touches any of these path
+# prefixes, the default critique rules can pass while the change
+# materially alters retrieval/scoring/graph algorithms. The hint
+# names the bench so the user includes it in their verification
+# loop. Order matters: first match wins (most specific first).
+_BENCH_RELEVANCE_RULES = [
+    (
+        ("src/roam/retrieve/", "src/roam/eval/"),
+        "pytest tests/test_retrieve_cross_repo.py + roam eval-retrieve --tasks bench/retrieve/roam_self.jsonl",
+    ),
+    (
+        ("src/roam/graph/pagerank.py", "src/roam/graph/clusters.py"),
+        "pytest tests/test_personalized_pagerank.py tests/test_fallback_contracts.py",
+    ),
+    (("src/roam/graph/",), "pytest tests/ -k graph_ -m 'not slow'"),
+    (
+        ("src/roam/languages/", "src/roam/index/parser.py"),
+        "pytest tests/test_languages.py tests/test_extractor_grammar_drift.py",
+    ),
+    (("src/roam/security/taint",), "pytest tests/test_taint_analysis.py tests/test_taint_classifier.py"),
+    (("src/roam/critique/",), "pytest tests/test_critique.py"),
+    (
+        ("src/roam/commands/cmd_oracle.py", "src/roam/commands/cmd_health.py"),
+        "pytest tests/test_oracle.py tests/test_commands_health.py",
+    ),
+]
+
+
+def _bench_relevance_hint(regions) -> str:
+    """Return a one-line bench/test suggestion when the diff touches a
+    structurally-significant path. ``regions`` is the
+    ``critique.checks.ChangedRegion`` list from the diff parser; we
+    look at each region's file path and pick the first matching rule.
+    """
+    paths = []
+    for r in regions:
+        path = getattr(r, "file_path", None) or getattr(r, "file", None) or ""
+        if path:
+            paths.append(path.replace("\\", "/"))
+    if not paths:
+        return ""
+    seen: set[str] = set()
+    for path in paths:
+        for prefixes, hint in _BENCH_RELEVANCE_RULES:
+            if any(path.startswith(p) or p in path for p in prefixes):
+                if hint in seen:
+                    return hint
+                seen.add(hint)
+                return hint
+    return ""
+
 
 @click.command()
 @click.option(
@@ -163,5 +214,17 @@ def critique(ctx, input_path, high_callers, intent_text):
                     click.echo(f"    {line}")
                 click.echo()
 
+        # Bench-relevance hint (dogfood notes 2026-05-01): when the diff
+        # touches files in the retrieve / graph / catalog hot path, the
+        # default rule set ("clones not edited", "blast radius") can
+        # legitimately say "no concerns" while the change quietly
+        # alters the structural-rerank scoring formula. Surfacing the
+        # bench command makes the verifier conversation include the
+        # one validation that actually exercises the modified code.
+        bench_hint = _bench_relevance_hint(regions)
+        if bench_hint:
+            click.echo()
+            click.echo(f"BENCH HINT: {bench_hint}")
+
     if result["severity_breakdown"].get("high", 0) > 0:
         ctx.exit(5)

{roam_code-12.2.0 → roam_code-12.3.1}/src/roam/commands/cmd_dead.py

@@ -358,6 +358,19 @@ def _group_dead(dead_items, by):
 # ---------------------------------------------------------------------------
 
 
+_TOOLING_PATH_HINTS = ("/dev/", "/benchmarks/", "/.github/", "\\dev\\", "\\benchmarks\\", "\\.github\\")
+
+
+def _is_tooling_path(path: str) -> bool:
+    """Same hint set as cmd_fan / cmd_smells. Excluded from dead-code
+    headline by default (dogfood notes 2026-05-01) — CI scripts are
+    expected to have unreferenced helper functions."""
+    if not path:
+        return False
+    p = "/" + path.replace("\\", "/")
+    return any(hint.replace("\\", "/") in p for hint in _TOOLING_PATH_HINTS)
+
+
 def _analyze_dead(conn):
     """Run the full dead code analysis.
 
@@ -366,6 +379,9 @@ def _analyze_dead(conn):
     rows = conn.execute(UNREFERENCED_EXPORTS).fetchall()
     # Exclude test files — their symbols are discovered by pytest, not imported
     rows = [r for r in rows if not _is_test_path(r["file_path"])]
+    # Exclude tooling/CI/benchmarks/dev — same default-exclusion that
+    # ``cmd_smells`` and ``cmd_fan`` apply.
+    rows = [r for r in rows if not _is_tooling_path(r["file_path"])]
     if not rows:
         return [], [], set()
 
@@ -1098,6 +1114,7 @@ def dead(
                 return
             if json_mode:
                 summary = {
+                    "verdict": "no dead exports",
                     "safe": 0,
                     "review": 0,
                     "intentional": 0,
@@ -1265,7 +1282,14 @@ def dead(
                     d["decay_score"] = ext["decay_score"]
                 return d
 
+            total = n_safe + n_review + n_intent
+            verdict = (
+                f"{total} dead export(s): {n_safe} safe, {n_review} review, {n_intent} intentional"
+                if total
+                else "no dead exports"
+            )
             summary = {
+                "verdict": verdict,
                 "safe": n_safe,
                 "review": n_review,
                 "intentional": n_intent,

{roam_code-12.2.0 → roam_code-12.3.1}/src/roam/commands/cmd_diagnose.py

@@ -315,6 +315,15 @@ def diagnose(ctx, name, depth):
 
         # Text output
         click.echo(f"VERDICT: {verdict}")
+        # Index-staleness hint (dogfood notes 2026-05-01): when index
+        # is older than HEAD, commit_count / churn columns are
+        # unreliable — surface this so the user knows whether to trust
+        # the numbers or re-index.
+        from roam.commands.resolve import index_staleness_hint as _stale_hint
+
+        _stale = _stale_hint()
+        if _stale:
+            click.echo(f"NOTE: {_stale}")
         sym_name = sym["qualified_name"] or sym["name"]
         click.echo(f"Diagnose: {sym_name}")
         click.echo(f"  {loc(target_metrics['file_path'], sym['line_start'])}")

{roam_code-12.2.0 → roam_code-12.3.1}/src/roam/commands/cmd_entry_points.py

@@ -103,7 +103,13 @@ _NAME_PATTERNS = [
     ("Scheduled", re.compile(r"cron|schedule|periodic|tick", re.IGNORECASE)),
     ("Message", re.compile(r"consume|subscriber|on_message|process_message", re.IGNORECASE)),
     ("CLI", re.compile(r"^cmd_|_command$|_cmd$", re.IGNORECASE)),
-    ("HTTP", re.compile(r"_view$|_endpoint$|_controller$|_handler$", re.IGNORECASE)),
+    # HTTP name patterns: only the strong endpoint/controller suffixes.
+    # ``_view$`` and ``_handler$`` matched too broadly — dogfood notes
+    # 2026-05-01 caught ``_extract_create_view`` (a SQL parser method)
+    # and ``error_handler`` (signal handler) being classified as HTTP
+    # routes. The decorator pattern above already catches genuine
+    # ``@app.route`` etc. — name fallback can be conservative.
+    ("HTTP", re.compile(r"_endpoint$|_controller$", re.IGNORECASE)),
 ]
 
 

{roam_code-12.2.0 → roam_code-12.3.1}/src/roam/commands/cmd_fan.py

@@ -107,12 +107,43 @@ _FRAMEWORK_NAMES = frozenset(
 )
 
 
+_TOOLING_PATH_HINTS = ("/dev/", "/benchmarks/", "/.github/", "\\dev\\", "\\benchmarks\\", "\\.github\\")
+
+
+def _is_tooling_path(path: str) -> bool:
+    """Return True for paths that belong to tooling/CI/benchmarks/dev.
+
+    Default-excluded from headline metrics so first-time users aren't
+    dominated by ``pr-comment.js`` and ``roam-bench.py`` rows.
+    Matches the hint set used by ``cmd_smells._file_role_lookup``.
+    """
+    if not path:
+        return False
+    p = "/" + path.replace("\\", "/")
+    return any(hint.replace("\\", "/") in p for hint in _TOOLING_PATH_HINTS)
+
+
+def _filter_tooling_rows(rows):
+    """Filter out rows whose ``file_path`` is in a tooling location."""
+    return [r for r in rows if not _is_tooling_path(r["file_path"] or "")]
+
+
 @click.command()
 @click.argument("mode", default="symbol", type=click.Choice(["symbol", "file"]))
 @click.option("-n", "count", default=20, help="Number of items to show")
 @click.option("--no-framework", is_flag=True, help="Filter out framework/boilerplate symbols")
+@click.option(
+    "--include-tooling",
+    is_flag=True,
+    default=False,
+    help=(
+        "Include CI scripts, dev tooling, build, and generated files. "
+        "Excluded by default — high fan-in in dev/.github/benchmarks "
+        "is expected and dominates the headline (dogfood notes 2026-05-01)."
+    ),
+)
 @click.pass_context
-def fan(ctx, mode, count, no_framework):
+def fan(ctx, mode, count, no_framework, include_tooling):
     """Show fan-in/fan-out: most connected symbols or files.
 
     Unlike ``coupling`` (which measures temporal co-change frequency), this
@@ -124,6 +155,10 @@ def fan(ctx, mode, count, no_framework):
     ensure_index()
 
     with open_db(readonly=True) as conn:
+        # Pull more rows than ``count`` when filtering, so the displayed
+        # top-N still has ``count`` entries after exclusions. 5x is a
+        # comfortable safety factor for typical tooling shares.
+        fetch_limit = count * 5 if not include_tooling else count
         if mode == "symbol":
             rows = conn.execute(
                 """
@@ -138,9 +173,13 @@ def fan(ctx, mode, count, no_framework):
                 ORDER BY total DESC
                 LIMIT ?
             """,
-                (count,),
+                (fetch_limit,),
             ).fetchall()
 
+            if not include_tooling:
+                rows = _filter_tooling_rows(rows)
+            rows = rows[:count]
+
             if no_framework:
                 rows = [r for r in rows if r["name"] not in _FRAMEWORK_NAMES]
 

{roam_code-12.2.0 → roam_code-12.3.1}/src/roam/commands/cmd_health.py

@@ -473,18 +473,34 @@ def health(ctx, no_framework, gate):
             """Sigmoid health factor: 1 for no issues, → 0 for many."""
             return math.exp(-value / scale) if scale > 0 else 1.0
 
-        god_critical = sum(1 for g in god_items if g.get("severity") == "CRITICAL")
-        god_signal = god_critical * 3 + len(god_items) * 0.5
-        bn_critical = sum(1 for b in bn_items if b.get("severity") == "CRITICAL")
-        bn_signal = bn_critical * 2 + len(bn_items) * 0.3
+        # Score signals — count *actionable* items only. Utilities
+        # (string/path/datetime helpers) are expected to have high fan-in
+        # and would dominate the formula otherwise. Per dogfood notes
+        # 2026-05-01: this repo had 50 god components total but 27 were
+        # expected utilities; the old formula penalised the score for
+        # all 50 and produced a misleading 2/100 verdict. The display
+        # already classifies them ("23 actionable, 27 expected utilities");
+        # the score should match the display.
+        god_actionable = [g for g in god_items if g.get("category") == "actionable"]
+        god_critical = sum(1 for g in god_actionable if g.get("severity") == "CRITICAL")
+        # Normalise by codebase size so a 14k-symbol repo with 23 actionable
+        # god components (0.16%) doesn't score the same as a 100-symbol
+        # repo with 23 (23%). 1k symbols is the unit; signal scales linearly.
+        size_norm = max(1.0, total_symbols / 1000.0)
+        god_signal = (god_critical * 3 + len(god_actionable) * 0.5) / size_norm
+        bn_actionable_items = [b for b in bn_items if b.get("category") == "actionable"]
+        bn_critical = sum(1 for b in bn_actionable_items if b.get("severity") == "CRITICAL")
+        bn_signal = (bn_critical * 2 + len(bn_actionable_items) * 0.3) / size_norm
 
         coverage_import = imported_coverage_overview(conn)
 
         # Base factors (weights sum to 1.0 before optional imported coverage).
+        # Scales tuned post-normalisation so a normal repo (low percent of
+        # actionable god components) scores in the 60-90 range.
         base_factors = [
             (_health_factor(tangle_ratio, 10), 0.30),  # tangle ratio
-            (_health_factor(god_signal, 5), 0.20),  # god components
-            (_health_factor(bn_signal, 4), 0.15),  # bottlenecks
+            (_health_factor(god_signal, 1.5), 0.20),  # god components (normalised /1k symbols)
+            (_health_factor(bn_signal, 1.0), 0.15),  # bottlenecks (normalised /1k symbols)
             (_health_factor(len(violations), 5), 0.15),  # layer violations
         ]
         # File-level health: map avg [0-10] to a factor
@@ -756,6 +772,14 @@ def health(ctx, no_framework, gate):
 
         # --- Text output ---
         click.echo(f"VERDICT: {verdict}\n")
+        # Index-staleness hint — only when relevant. Surfaces here
+        # because git_file_changes feed health's tangle/coupling/churn
+        # signals; an out-of-date index quietly degrades all of them.
+        from roam.commands.resolve import index_staleness_hint as _stale_hint
+
+        _stale = _stale_hint()
+        if _stale:
+            click.echo(f"NOTE: {_stale}\n")
         issue_count = len(cycles) + len(god_items) + len(bn_items) + len(violations)
         parts = []
         if cycles:

{roam_code-12.2.0 → roam_code-12.3.1}/src/roam/commands/cmd_oracle.py

@@ -87,33 +87,57 @@ def oracle_route_exists(conn: sqlite3.Connection, path: str) -> tuple[bool, str]
 
 
 def oracle_is_test_only(conn: sqlite3.Connection, name: str) -> tuple[bool, str]:
-    """Are ALL callers of this symbol in test files?
-
-    A symbol with no callers at all returns ``False`` (no evidence either
-    way). A symbol whose every caller's file role is ``test`` (per
-    ``files.file_role``) returns ``True``.
+    """Is this symbol used only by test code?
+
+    Resolution order (matches dogfood expectations 2026-05-01):
+
+    1. **Symbol lives in a test file** → ``True``. The previous heuristic
+       was "all callers in test files", but a test method like
+       ``test_check_count`` has zero callers (pytest invokes it by
+       reflection), and the heuristic returned ``False`` for the most
+       canonically test-only thing in the codebase. We now check the
+       symbol's *own* ``file_role`` first — anything in
+       ``file_role='test'`` is test-only by definition.
+    2. **Symbol is in a non-test file with all callers in test files**
+       → ``True``. Catches helpers that live in production but are
+       only ever called from tests (genuinely test-only).
+    3. **Symbol has no callers and is in a non-test file** → ``False``
+       with a clearer "orphan" reason than before.
     """
     if not name:
         return False, "empty query"
     target_rows = conn.execute(
-        "SELECT id FROM symbols WHERE name = ? OR qualified_name = ?",
+        """
+        SELECT s.id, COALESCE(f.file_role, 'unknown') AS role
+        FROM symbols s
+        JOIN files f ON f.id = s.file_id
+        WHERE s.name = ? OR s.qualified_name = ?
+        """,
         (name, name),
     ).fetchall()
     if not target_rows:
         return False, f"no symbol named '{name}'"
-    target_ids = [int(r[0]) for r in target_rows]
 
+    # 1) Symbol's own file_role is 'test' → trivially test-only.
+    own_test = [r for r in target_rows if r[1] == "test"]
+    if own_test and len(own_test) == len(target_rows):
+        return True, "symbol lives in a test file (file_role='test')"
+    # Mixed (e.g. same name in test + source) — fall through to caller
+    # analysis so the answer reflects actual usage.
+
+    target_ids = [int(r[0]) for r in target_rows]
     placeholders = ",".join("?" * len(target_ids))
     caller_rows = conn.execute(
         f"SELECT s.id, COALESCE(f.file_role, 'unknown') AS role "
         f"FROM edges e "
         f"JOIN symbols s ON s.id = e.source_id "
         f"JOIN files f ON f.id = s.file_id "
-        f"WHERE e.target_id IN ({placeholders}) AND e.kind IN ('calls', 'references')",
+        f"WHERE e.target_id IN ({placeholders}) AND e.kind IN ('call', 'reference', 'calls', 'references')",
         target_ids,
     ).fetchall()
     if not caller_rows:
-        return False, f"no callers found for '{name}' (orphan)"
+        # 3) No callers AND no callees lives in a test file ⇒ orphan in source.
+        return False, f"no callers found for '{name}' (orphan in source)"
     test_count = sum(1 for r in caller_rows if r[1] == "test")
     total = len(caller_rows)
     if test_count == total:
@@ -143,24 +167,42 @@ def oracle_is_reachable_from_entry(conn: sqlite3.Connection, name: str, *, max_h
         return False, f"no symbol named '{name}'"
     target_ids = {int(r[0]) for r in target_rows}
 
-    # Pull entry symbol ids. Conservative: prefer explicit `is_entry=1`,
-    # fall back to file_role='entry'.
+    # Entry-point definition (dogfood notes 2026-05-01, two iterations):
+    #
+    # First attempt — files with no incoming ``file_edges``. Caught the
+    # previous bug (``no entry-point symbols indexed`` on every query)
+    # but mis-classified ``cli`` itself: ``src/roam/cli.py`` IS imported
+    # by tests + internal helpers so it had incoming edges and wasn't
+    # an entry point. The user expects ``is-reachable cli`` to be True.
+    #
+    # Second attempt — same import-graph definition PLUS name-based
+    # fallback for canonical entry symbols (``cli``, ``main``,
+    # ``__main__``, ``run``, ``app``, ``serve``). Anything with one of
+    # these names IS treated as an entry point regardless of whether
+    # someone imported its file. Catches the "main is the entry point
+    # but tests import it" case without false-positives elsewhere.
     try:
-        entry_rows = conn.execute("SELECT s.id FROM symbols s WHERE s.is_entry = 1").fetchall()
+        entry_rows = conn.execute(
+            """
+            SELECT s.id FROM symbols s
+            JOIN files f ON f.id = s.file_id
+            WHERE f.id NOT IN (SELECT DISTINCT target_file_id FROM file_edges)
+            """
+        ).fetchall()
         entry_ids = {int(r[0]) for r in entry_rows}
     except sqlite3.OperationalError:
         entry_ids = set()
-    if not entry_ids:
-        try:
-            entry_rows = conn.execute(
-                "SELECT s.id FROM symbols s JOIN files f ON f.id = s.file_id WHERE COALESCE(f.file_role, '') = 'entry'"
-            ).fetchall()
-            entry_ids = {int(r[0]) for r in entry_rows}
-        except sqlite3.OperationalError:
-            entry_ids = set()
+
+    try:
+        named_entry_rows = conn.execute(
+            "SELECT id FROM symbols WHERE name IN ('cli', 'main', '__main__', 'run', 'app', 'serve', 'entrypoint')"
+        ).fetchall()
+        entry_ids.update(int(r[0]) for r in named_entry_rows)
+    except sqlite3.OperationalError:
+        pass
 
     if not entry_ids:
-        return False, "no entry-point symbols indexed (run `roam index` first)"
+        return False, "no entry-point symbols indexed (run `roam init` to (re)build the index)"
 
     if entry_ids & target_ids:
         return True, "target is itself an entry point"
@@ -176,7 +218,7 @@ def oracle_is_reachable_from_entry(conn: sqlite3.Connection, name: str, *, max_h
             rows = conn.execute(
                 f"SELECT target_id FROM edges "
                 f"WHERE source_id IN ({placeholders}) "
-                f"  AND kind IN ('calls', 'references')",
+                f"  AND kind IN ('call', 'reference', 'calls', 'references')",
                 chunk,
             ).fetchall()
             for r in rows:

{roam_code-12.2.0 → roam_code-12.3.1}/src/roam/commands/cmd_preflight.py

@@ -106,6 +106,42 @@ def _overall_risk(*severities: str) -> str:
     return "LOW"
 
 
+def _risk_driver(blast, tests, compl, coupl, convs, fitns) -> str:
+    """Identify the row driving the overall risk verdict.
+
+    Returns a one-line summary like ``complexity (cc=17, HIGH)`` so
+    an agent reading the preflight output knows *why* the overall
+    verdict is what it is — it doesn't have to scan all six rows
+    looking for the worst severity.
+
+    Tie-break by actionability: complexity > fitness > tests > coupling
+    > blast > conventions. A complexity warning is more actionable than
+    a convention warning even at equal severity.
+    """
+    rows = [
+        ("complexity", compl, f"cc={compl['max_cognitive_complexity']:.0f}"),
+        ("fitness", fitns, f"{fitns.get('rules_failed', 0)} rules would fail"),
+        ("tests", tests, f"{tests.get('direct', 0)} direct, {tests.get('transitive', 0)} transitive"),
+        ("coupling", coupl, f"{coupl.get('coupled_files', 0)} coupled files"),
+        (
+            "blast radius",
+            blast,
+            f"{blast.get('affected_symbols', 0)} symbols in {blast.get('affected_files', 0)} files",
+        ),
+        ("conventions", convs, f"{convs.get('violation_count', 0)} violations"),
+    ]
+    # Find max severity
+    worst: tuple[int, str, str] | None = None
+    for label, row, detail in rows:
+        sev = row.get("severity", "OK").upper()
+        order = _SEVERITY_ORDER.get(sev, 0)
+        if order <= 1:  # OK / LOW — not driving the verdict
+            continue
+        if worst is None or order > worst[0]:
+            worst = (order, label, f"{label} ({detail}, {sev})")
+    return worst[2] if worst else ""
+
+
 def _severity_tag(sev: str) -> str:
     return f"[{sev}]"
 
@@ -708,6 +744,15 @@ def preflight(ctx, target, staged):
         # Overall
         click.echo(f"\n  Overall risk: {risk}")
 
+        # Risk driver — name the row that's pushing the verdict so an
+        # agent doesn't have to deduce it (dogfood notes 2026-05-01).
+        # Pick the highest-severity row, breaking ties by category
+        # priority (complexity > fitness > tests > coupling > blast >
+        # conventions — most actionable first).
+        driver = _risk_driver(blast, tests, compl, coupl, convs, fitns)
+        if driver:
+            click.echo(f"  Risk driver:  {driver}")
+
         # Suggested tests
         if tests["pytest_command"]:
             click.echo(f"  Suggested tests: {tests['pytest_command']}")