roam-code 12.18__tar.gz → 12.19__tar.gz

{roam_code-12.18/src/roam_code.egg-info → roam_code-12.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roam-code
-Version: 12.18
+Version: 12.19
 Summary: Instant codebase comprehension for AI coding agents
 Author: CosmoHac
 License-Expression: MIT
@@ -62,9 +62,9 @@ Dynamic: license-file
 
 **Architectural sight for AI coding agents — before they edit.**
 
-A local code graph (SQLite + tree-sitter + git history) that gives any agent — Claude Code, Cursor, Aider, Continue, your own — five high-leverage verbs: `understand`, `retrieve`, `context`, `preflight`, `critique`. The other 172 specialised commands are advanced surface for specialised workflows.
+A local code graph (SQLite + tree-sitter + git history) that gives any agent — Claude Code, Cursor, Aider, Continue, your own — five high-leverage verbs: `understand`, `retrieve`, `context`, `preflight`, `critique`. The other 173 specialised commands are advanced surface for specialised workflows.
 
-*177 commands · 123 MCP tools · 27 languages · 100% local · zero API keys*
+*178 commands · 128 MCP tools · 27 languages · 100% local · zero API keys*
 
 [![PyPI version](https://img.shields.io/pypi/v/roam-code?style=flat-square&color=blue)](https://pypi.org/project/roam-code/)
 [![GitHub stars](https://img.shields.io/github/stars/Cranot/roam-code?style=flat-square)](https://github.com/Cranot/roam-code/stargazers)
@@ -156,7 +156,7 @@ $ roam diff                    # blast radius of uncommitted changes
 - **`personalized_pagerank()`** in `graph/pagerank.py`: NetworkX `personalization=` wrapper with empty-seed fallback to global PR; biases ranking toward query-relevant nodes for the retrieve reranker.
 - **`.roam/config.toml`** (new): zero-dep TOML loader (stdlib `tomllib` → `tomli` → in-tree subset parser). Tunable retrieve weights (`alpha`/`beta`/`gamma`/`delta`/`epsilon`), `tokens_per_line`, `lexical_baseline`, `first_stage_token_cap`, `default_budget`, `default_k`, `default_rerank`.
 - **DX corrections from dogfood pass**: `roam --detail <cmd>` is the canonical group-level flag; misleading "use --detail" hints in 7 commands rewritten to point users at `roam --detail <cmd>`. `--top N` aliased on `complexity`/`algo`/`rules` (`--top 0` means unlimited on `rules`). `roam fingerprint` no longer refuses graphs ≥5,000 symbols (new soft-warn threshold 20k, hard cap 100k).
-- **177 CLI commands, 123 MCP tools** (`fleet`, `ask`, `workflow`, `cga`, `eval-retrieve` remain CLI-only; v12 exposes `roam_retrieve`, `roam_critique`, `roam_fleet_plan`, plus 5 v12.1 boolean oracles (`roam_oracle_*`), `roam_taint_classify`, `roam_pytest_fixtures`, and `roam_hover` as MCP tools). 35-tool `core` preset is the default for token-budget-conscious clients.
+- **177 CLI commands, 128 MCP tools** (`fleet`, `ask`, `workflow`, `cga`, `eval-retrieve` remain CLI-only; v12 exposes `roam_retrieve`, `roam_critique`, `roam_fleet_plan`, plus 5 v12.1 boolean oracles (`roam_oracle_*`), `roam_taint_classify`, `roam_pytest_fixtures`, and `roam_hover` as MCP tools). 35-tool `core` preset is the default for token-budget-conscious clients.
 
 ## What's New in v11
 
@@ -327,7 +327,7 @@ roam health
 
 ## Commands
 
-**Lead with the 5 verbs.** The [5 core commands](#core-commands) cover ~80% of agent workflows: `understand`, `context`, `retrieve`, `preflight`, `critique`. The remaining 172 commands are detail surface for specialised workflows (taint, fleet, cga, oracle, eval, …) — they're called by agents on demand, not memorised. This is intentional design; under the hood the canonical surface is **177 commands organised into 7 categories** (plus 6 aliases for muscle memory: `algo` → `math`, `weather` → `churn`, `digest` / `snapshot` / `trend` → `trends`, `onboard` → `understand`), but you don't need to know that to start.
+**Lead with the 5 verbs.** The [5 core commands](#core-commands) cover ~80% of agent workflows: `understand`, `context`, `retrieve`, `preflight`, `critique`. The remaining 173 commands are detail surface for specialised workflows (taint, fleet, cga, oracle, eval, …) — they're called by agents on demand, not memorised. This is intentional design; under the hood the canonical surface is **178 commands organised into 7 categories** (plus 6 aliases for muscle memory: `algo` → `math`, `weather` → `churn`, `digest` / `snapshot` / `trend` → `trends`, `onboard` → `understand`), but you don't need to know that to start.
 
 <details>
 <summary><strong>Full command reference</strong></summary>
@@ -375,6 +375,7 @@ roam health
 | `roam api [--scope <dir>]` | List the public API surface (exported public symbols + signatures) |
 | `roam exit-codes` | List every roam exit code with its meaning |
 | `roam version [--check]` | Show installed version; with `--check` also queries PyPI for newer releases |
+| `roam audit [--brief]` | One-shot AI Agent Readiness Audit — chains health + debt + dead + risk + test-pyramid + api into a single envelope |
 | `roam disambiguate <name>` | List every symbol matching the name with file/line/kind/signature/docstring snippet to pick the right one |
 | `roam pre-commit [--install\|--print]` | Install or preview a roam-critique git pre-commit hook |
 | `roam mcp-status` | MCP server health: preset, registered tools, backpressure limits, cache entries, watcher state |
@@ -992,7 +993,7 @@ ROAM_MCP_LITE=0 roam mcp
 Core preset tools: `roam_affected_tests`, `roam_batch_get`, `roam_batch_search`, `roam_complete`, `roam_complexity_report`, `roam_context`, `roam_dead_code`, `roam_deps`, `roam_diagnose`, `roam_diagnose_issue`, `roam_diff`, `roam_expand_toolset`, `roam_explore`, `roam_file_info`, `roam_health`, `roam_impact`, `roam_pr_risk`, `roam_preflight`, `roam_prepare_change`, `roam_review_change`, `roam_search_symbol`, `roam_syntax_check`, `roam_trace`, `roam_understand`, `roam_uses`.
 
 <details>
-<summary><strong>MCP tool list (all 123)</strong></summary>
+<summary><strong>MCP tool list (all 128)</strong></summary>
 
 | Tool | Description |
 |------|-------------|
@@ -1116,6 +1117,11 @@ Core preset tools: `roam_affected_tests`, `roam_batch_get`, `roam_batch_search`,
 | `roam_reset` | Reset the roam index and cached data |
 | `roam_clean` | Remove stale or orphaned index entries |
 | `roam_catalog` | Machine-readable list of every registered MCP tool with capability flags (read_only / destructive / core) |
+| `roam_alerts` | Active health alerts: thresholds breached on tangle, complexity, churn, or coverage |
+| `roam_timeline` | Chronological commits that touched the file owning a symbol |
+| `roam_test_impact` | Tests transitively reachable from changed symbols (sharper than affected_tests) |
+| `roam_disambiguate` | List every symbol matching a name with file/line/kind/PageRank — pick the right overload |
+| `roam_why_fail` | Triage a failing test/symbol: recently-changed reachable symbols ranked by recency |
 | `roam_batch_search` | Batch symbol search: run multiple pattern queries in a single call |
 | `roam_batch_get` | Batch context retrieval: fetch multiple symbols/files in a single call |
 | `roam_dev_profile` | Developer productivity profile: commit patterns, specialization, and impact |
@@ -1728,7 +1734,7 @@ Optional: Local semantic ONNX stack (`numpy`, `onnxruntime`, `tokenizers`) via `
 ### Shipped
 
 - [x] MCP v2 agent surface: in-process execution, compound operations, presets, schemas, annotations, and compatibility profiles.
-- [x] Full command and MCP inventory parity in docs: 177 canonical CLI commands and 123 MCP tools.
+- [x] Full command and MCP inventory parity in docs: 177 canonical CLI commands and 128 MCP tools.
 - [x] CI hardening: composite action, changed-only mode, trend-aware gates, sticky PR updater, and SARIF guardrails.
 - [x] Performance foundation: FTS5/BM25 search, O(changed) incremental indexing, DB/index optimizations.
 - [x] Agent governance suite: `vibe-check`, `ai-readiness`, `verify`, `ai-ratio`, `duplicates`, advanced `algo` scoring/SARIF.

{roam_code-12.18 → roam_code-12.19}/README.md

@@ -4,9 +4,9 @@
 
 **Architectural sight for AI coding agents — before they edit.**
 
-A local code graph (SQLite + tree-sitter + git history) that gives any agent — Claude Code, Cursor, Aider, Continue, your own — five high-leverage verbs: `understand`, `retrieve`, `context`, `preflight`, `critique`. The other 172 specialised commands are advanced surface for specialised workflows.
+A local code graph (SQLite + tree-sitter + git history) that gives any agent — Claude Code, Cursor, Aider, Continue, your own — five high-leverage verbs: `understand`, `retrieve`, `context`, `preflight`, `critique`. The other 173 specialised commands are advanced surface for specialised workflows.
 
-*177 commands · 123 MCP tools · 27 languages · 100% local · zero API keys*
+*178 commands · 128 MCP tools · 27 languages · 100% local · zero API keys*
 
 [![PyPI version](https://img.shields.io/pypi/v/roam-code?style=flat-square&color=blue)](https://pypi.org/project/roam-code/)
 [![GitHub stars](https://img.shields.io/github/stars/Cranot/roam-code?style=flat-square)](https://github.com/Cranot/roam-code/stargazers)
@@ -98,7 +98,7 @@ $ roam diff                    # blast radius of uncommitted changes
 - **`personalized_pagerank()`** in `graph/pagerank.py`: NetworkX `personalization=` wrapper with empty-seed fallback to global PR; biases ranking toward query-relevant nodes for the retrieve reranker.
 - **`.roam/config.toml`** (new): zero-dep TOML loader (stdlib `tomllib` → `tomli` → in-tree subset parser). Tunable retrieve weights (`alpha`/`beta`/`gamma`/`delta`/`epsilon`), `tokens_per_line`, `lexical_baseline`, `first_stage_token_cap`, `default_budget`, `default_k`, `default_rerank`.
 - **DX corrections from dogfood pass**: `roam --detail <cmd>` is the canonical group-level flag; misleading "use --detail" hints in 7 commands rewritten to point users at `roam --detail <cmd>`. `--top N` aliased on `complexity`/`algo`/`rules` (`--top 0` means unlimited on `rules`). `roam fingerprint` no longer refuses graphs ≥5,000 symbols (new soft-warn threshold 20k, hard cap 100k).
-- **177 CLI commands, 123 MCP tools** (`fleet`, `ask`, `workflow`, `cga`, `eval-retrieve` remain CLI-only; v12 exposes `roam_retrieve`, `roam_critique`, `roam_fleet_plan`, plus 5 v12.1 boolean oracles (`roam_oracle_*`), `roam_taint_classify`, `roam_pytest_fixtures`, and `roam_hover` as MCP tools). 35-tool `core` preset is the default for token-budget-conscious clients.
+- **177 CLI commands, 128 MCP tools** (`fleet`, `ask`, `workflow`, `cga`, `eval-retrieve` remain CLI-only; v12 exposes `roam_retrieve`, `roam_critique`, `roam_fleet_plan`, plus 5 v12.1 boolean oracles (`roam_oracle_*`), `roam_taint_classify`, `roam_pytest_fixtures`, and `roam_hover` as MCP tools). 35-tool `core` preset is the default for token-budget-conscious clients.
 
 ## What's New in v11
 
@@ -269,7 +269,7 @@ roam health
 
 ## Commands
 
-**Lead with the 5 verbs.** The [5 core commands](#core-commands) cover ~80% of agent workflows: `understand`, `context`, `retrieve`, `preflight`, `critique`. The remaining 172 commands are detail surface for specialised workflows (taint, fleet, cga, oracle, eval, …) — they're called by agents on demand, not memorised. This is intentional design; under the hood the canonical surface is **177 commands organised into 7 categories** (plus 6 aliases for muscle memory: `algo` → `math`, `weather` → `churn`, `digest` / `snapshot` / `trend` → `trends`, `onboard` → `understand`), but you don't need to know that to start.
+**Lead with the 5 verbs.** The [5 core commands](#core-commands) cover ~80% of agent workflows: `understand`, `context`, `retrieve`, `preflight`, `critique`. The remaining 173 commands are detail surface for specialised workflows (taint, fleet, cga, oracle, eval, …) — they're called by agents on demand, not memorised. This is intentional design; under the hood the canonical surface is **178 commands organised into 7 categories** (plus 6 aliases for muscle memory: `algo` → `math`, `weather` → `churn`, `digest` / `snapshot` / `trend` → `trends`, `onboard` → `understand`), but you don't need to know that to start.
 
 <details>
 <summary><strong>Full command reference</strong></summary>
@@ -317,6 +317,7 @@ roam health
 | `roam api [--scope <dir>]` | List the public API surface (exported public symbols + signatures) |
 | `roam exit-codes` | List every roam exit code with its meaning |
 | `roam version [--check]` | Show installed version; with `--check` also queries PyPI for newer releases |
+| `roam audit [--brief]` | One-shot AI Agent Readiness Audit — chains health + debt + dead + risk + test-pyramid + api into a single envelope |
 | `roam disambiguate <name>` | List every symbol matching the name with file/line/kind/signature/docstring snippet to pick the right one |
 | `roam pre-commit [--install\|--print]` | Install or preview a roam-critique git pre-commit hook |
 | `roam mcp-status` | MCP server health: preset, registered tools, backpressure limits, cache entries, watcher state |
@@ -934,7 +935,7 @@ ROAM_MCP_LITE=0 roam mcp
 Core preset tools: `roam_affected_tests`, `roam_batch_get`, `roam_batch_search`, `roam_complete`, `roam_complexity_report`, `roam_context`, `roam_dead_code`, `roam_deps`, `roam_diagnose`, `roam_diagnose_issue`, `roam_diff`, `roam_expand_toolset`, `roam_explore`, `roam_file_info`, `roam_health`, `roam_impact`, `roam_pr_risk`, `roam_preflight`, `roam_prepare_change`, `roam_review_change`, `roam_search_symbol`, `roam_syntax_check`, `roam_trace`, `roam_understand`, `roam_uses`.
 
 <details>
-<summary><strong>MCP tool list (all 123)</strong></summary>
+<summary><strong>MCP tool list (all 128)</strong></summary>
 
 | Tool | Description |
 |------|-------------|
@@ -1058,6 +1059,11 @@ Core preset tools: `roam_affected_tests`, `roam_batch_get`, `roam_batch_search`,
 | `roam_reset` | Reset the roam index and cached data |
 | `roam_clean` | Remove stale or orphaned index entries |
 | `roam_catalog` | Machine-readable list of every registered MCP tool with capability flags (read_only / destructive / core) |
+| `roam_alerts` | Active health alerts: thresholds breached on tangle, complexity, churn, or coverage |
+| `roam_timeline` | Chronological commits that touched the file owning a symbol |
+| `roam_test_impact` | Tests transitively reachable from changed symbols (sharper than affected_tests) |
+| `roam_disambiguate` | List every symbol matching a name with file/line/kind/PageRank — pick the right overload |
+| `roam_why_fail` | Triage a failing test/symbol: recently-changed reachable symbols ranked by recency |
 | `roam_batch_search` | Batch symbol search: run multiple pattern queries in a single call |
 | `roam_batch_get` | Batch context retrieval: fetch multiple symbols/files in a single call |
 | `roam_dev_profile` | Developer productivity profile: commit patterns, specialization, and impact |
@@ -1670,7 +1676,7 @@ Optional: Local semantic ONNX stack (`numpy`, `onnxruntime`, `tokenizers`) via `
 ### Shipped
 
 - [x] MCP v2 agent surface: in-process execution, compound operations, presets, schemas, annotations, and compatibility profiles.
-- [x] Full command and MCP inventory parity in docs: 177 canonical CLI commands and 123 MCP tools.
+- [x] Full command and MCP inventory parity in docs: 177 canonical CLI commands and 128 MCP tools.
 - [x] CI hardening: composite action, changed-only mode, trend-aware gates, sticky PR updater, and SARIF guardrails.
 - [x] Performance foundation: FTS5/BM25 search, O(changed) incremental indexing, DB/index optimizations.
 - [x] Agent governance suite: `vibe-check`, `ai-readiness`, `verify`, `ai-ratio`, `duplicates`, advanced `algo` scoring/SARIF.

{roam_code-12.18 → roam_code-12.19}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "roam-code"
-version = "12.18"
+version = "12.19"
 description = "Instant codebase comprehension for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{roam_code-12.18 → roam_code-12.19}/src/roam/cli.py

@@ -127,6 +127,7 @@ _COMMANDS = {
     "exit-codes": ("roam.commands.cmd_exit_codes", "exit_codes"),
     "version": ("roam.commands.cmd_version", "version"),
     "disambiguate": ("roam.commands.cmd_disambiguate", "disambiguate"),
+    "audit": ("roam.commands.cmd_audit", "audit"),
     "pre-commit": ("roam.commands.cmd_pre_commit", "pre_commit"),
     "mcp-status": ("roam.commands.cmd_mcp_status", "mcp_status"),
     "test-impact": ("roam.commands.cmd_test_impact", "test_impact"),
@@ -245,6 +246,7 @@ _CATEGORIES = {
         "mcp-status",
         "ci-setup",
         "adrs",
+        "audit",
         "changelog",
         "exit-codes",
         "help-search",

{roam_code-12.18 → roam_code-12.19}/src/roam/commands/cmd_adversarial.py

@@ -12,7 +12,7 @@ import click
 
 from roam.commands.changed_files import get_changed_files, resolve_changed_to_db
 from roam.commands.resolve import ensure_index
-from roam.db.connection import find_project_root, open_db
+from roam.db.connection import batched_in, find_project_root, open_db
 from roam.output.formatter import abbrev_kind, json_envelope, loc, to_json
 
 # ---------------------------------------------------------------------------
@@ -308,28 +308,30 @@ def _check_cross_cluster(conn, changed_sym_ids):
 
 
 def _check_orphaned_symbols(conn, changed_sym_ids):
-    """Check for symbols in changed files with zero incoming edges."""
+    """Check for symbols in changed files with zero incoming edges.
+
+    Pass 94 — single batched query for in-degree + symbol metadata
+    instead of two queries per changed symbol.
+    """
     challenges = []
     if not changed_sym_ids:
         return challenges
 
-    for sid in changed_sym_ids:
-        try:
-            row = conn.execute("SELECT COUNT(*) as cnt FROM edges WHERE target_id = ?", (sid,)).fetchone()
-        except Exception:
-            continue
-        if not row or row["cnt"] != 0:
-            continue
+    sid_list = list(changed_sym_ids)
+    # One query per batch instead of two queries per symbol.
+    rows = batched_in(
+        conn,
+        "SELECT s.id, s.name, s.kind, f.path AS file_path, s.line_start, "
+        "       (SELECT COUNT(*) FROM edges WHERE target_id = s.id) AS in_degree "
+        "  FROM symbols s JOIN files f ON s.file_id = f.id "
+        " WHERE s.id IN ({ph})",
+        sid_list,
+    )
+    sym_by_id = {r["id"]: r for r in rows if r["in_degree"] == 0}
 
-        try:
-            sym = conn.execute(
-                "SELECT s.name, s.kind, f.path as file_path, s.line_start "
-                "FROM symbols s JOIN files f ON s.file_id = f.id WHERE s.id = ?",
-                (sid,),
-            ).fetchone()
-        except Exception:
-            continue
-        if not sym:
+    for sid in changed_sym_ids:
+        sym = sym_by_id.get(sid)
+        if sym is None:
             continue
 
         # Only flag substantive symbols
@@ -371,25 +373,23 @@ def _check_high_fan_out(conn, changed_sym_ids):
 
     _FAN_OUT_THRESHOLD = 10
 
-    for sid in changed_sym_ids:
-        try:
-            row = conn.execute("SELECT COUNT(*) as cnt FROM edges WHERE source_id = ?", (sid,)).fetchone()
-        except Exception:
-            continue
-        if not row or row["cnt"] <= _FAN_OUT_THRESHOLD:
-            continue
+    # Pass 94 — single batched query for fan-out + metadata.
+    sid_list = list(changed_sym_ids)
+    rows = batched_in(
+        conn,
+        "SELECT s.id, s.name, s.kind, f.path AS file_path, s.line_start, "
+        "       (SELECT COUNT(*) FROM edges WHERE source_id = s.id) AS fan_out "
+        "  FROM symbols s JOIN files f ON s.file_id = f.id "
+        " WHERE s.id IN ({ph})",
+        sid_list,
+    )
+    sym_by_id = {r["id"]: r for r in rows if r["fan_out"] > _FAN_OUT_THRESHOLD}
 
-        fan_out = row["cnt"]
-        try:
-            sym = conn.execute(
-                "SELECT s.name, s.kind, f.path as file_path, s.line_start "
-                "FROM symbols s JOIN files f ON s.file_id = f.id WHERE s.id = ?",
-                (sid,),
-            ).fetchone()
-        except Exception:
-            continue
-        if not sym:
+    for sid in changed_sym_ids:
+        sym = sym_by_id.get(sid)
+        if sym is None:
             continue
+        fan_out = sym["fan_out"]
 
         file_path = (sym["file_path"] or "").replace("\\", "/")
         name = sym["name"] or ""

{roam_code-12.18 → roam_code-12.19}/src/roam/commands/cmd_affected.py

@@ -243,11 +243,17 @@ def affected(ctx, base_ref, max_depth, use_changed):
 
         changed_paths = set(file_map.keys())
 
-        # Collect all symbol IDs in changed files
+        # Collect all symbol IDs in changed files. Pass 94 — single
+        # batched IN-clause replaces N round-trips (was one query per
+        # changed file; now one query for the whole set).
         start_sym_ids = set()
-        for path, fid in file_map.items():
-            syms = conn.execute("SELECT id FROM symbols WHERE file_id = ?", (fid,)).fetchall()
-            start_sym_ids.update(s["id"] for s in syms)
+        if file_map:
+            sym_rows = batched_in(
+                conn,
+                "SELECT id FROM symbols WHERE file_id IN ({ph})",
+                list(file_map.values()),
+            )
+            start_sym_ids.update(s["id"] for s in sym_rows)
 
         # BFS forward to find all dependents
         reachable = _bfs_forward_with_depth(conn, start_sym_ids, max_depth)

{roam_code-12.18 → roam_code-12.19}/src/roam/commands/cmd_agent_export.py

@@ -699,8 +699,14 @@ def _write_with_preserve(filepath, content):
     is_flag=True,
     help="Write directly to project root (CLAUDE/AGENTS/CODEX/GEMINI/.cursorrules)",
 )
+@click.option(
+    "--brief",
+    "brief_mode",
+    is_flag=True,
+    help="Pass 100 — emit a compact summary (top-level fields only) instead of the full agent doc.",
+)
 @click.pass_context
-def agent_export(ctx, output, fmt, profile, bundle, write_flag):
+def agent_export(ctx, output, fmt, profile, bundle, write_flag, brief_mode):
     """Generate an AI agent context file from the roam index.
 
     Produces a concise markdown document with architecture, key files,
@@ -781,6 +787,36 @@ def agent_export(ctx, output, fmt, profile, bundle, write_flag):
 
     # JSON output
     if json_mode:
+        envelope_kwargs = dict(
+            format=formats[0],
+            formats=formats,
+            profile=profile,
+            bundle=bundle,
+            project_name=project_name,
+        )
+        if not brief_mode:
+            # Pass 100 — full payload only when --brief is OFF.
+            envelope_kwargs.update(
+                languages=languages,
+                stats=stats,
+                directory_layout=layout,
+                key_files=key_files,
+                entry_points=entry_points,
+                hotspots=hotspots,
+                test_info=test_info,
+                health_summary=(
+                    {
+                        "score": health.get("health_score"),
+                        "cycles": health.get("cycles", 0),
+                        "god_components": health.get("god_components", 0),
+                        "dead_exports": health.get("dead_exports", 0),
+                    }
+                    if health
+                    else None
+                ),
+                layers=layers,
+                clusters=clusters,
+            )
         click.echo(
             to_json(
                 json_envelope(
@@ -794,29 +830,9 @@ def agent_export(ctx, output, fmt, profile, bundle, write_flag):
                         "sections": section_count,
                         "files": stats["files"],
                         "symbols": stats["symbols"],
+                        "brief": brief_mode,
                     },
-                    format=formats[0],
-                    formats=formats,
-                    profile=profile,
-                    bundle=bundle,
-                    project_name=project_name,
-                    languages=languages,
-                    stats=stats,
-                    directory_layout=layout,
-                    key_files=key_files,
-                    entry_points=entry_points,
-                    hotspots=hotspots,
-                    test_info=test_info,
-                    health_summary={
-                        "score": health.get("health_score"),
-                        "cycles": health.get("cycles", 0),
-                        "god_components": health.get("god_components", 0),
-                        "dead_exports": health.get("dead_exports", 0),
-                    }
-                    if health
-                    else None,
-                    layers=layers,
-                    clusters=clusters,
+                    **envelope_kwargs,
                 )
             )
         )

roam_code-12.19/src/roam/commands/cmd_audit.py

@@ -0,0 +1,169 @@
+"""``roam audit`` — AI Agent Readiness Audit.
+
+Pass 97 — Priority 1 strategic blocker per build_priorities.md. Chains
+``index → describe → health → risk → dead → owner → test-map → pr-risk``
+into a single structured-JSON envelope. The artifact paying customers
+buy: a one-shot audit that calibrates how ready a codebase is for
+agent-driven work.
+
+Sections:
+
+  - ``health`` — composite health score with category breakdown
+  - ``debt``   — total estimated debt + top hotspots
+  - ``dead``   — unused-symbol count + top wasted-LOC files
+  - ``risk``   — surface high-risk files (churn × complexity × fan-in)
+  - ``test_pyramid`` — unit/integration/e2e/smoke distribution
+  - ``coverage`` — imported-coverage % when available
+  - ``api``    — count of public symbols (the agent-facing surface)
+
+Each section runs the corresponding sub-command in --json mode and
+extracts a small set of high-signal fields. Failures from individual
+sections are surfaced as ``{"error": ...}`` rows so the audit never
+fails the whole report.
+"""
+
+from __future__ import annotations
+
+import json as _json
+
+import click
+from click.testing import CliRunner
+
+from roam.commands.resolve import ensure_index
+from roam.output.formatter import json_envelope, to_json
+
+
+def _capture(args: list[str]) -> dict:
+    """Invoke a roam subcommand in --json mode in-process."""
+    from roam.cli import cli
+
+    runner = CliRunner()
+    result = runner.invoke(cli, ["--json", *args])
+    if result.exit_code not in (0, 5):  # 5 = gate failure (still produces JSON)
+        return {
+            "_error": f"exit {result.exit_code}",
+            "_command": args,
+            "_output_head": (result.output or "")[:200],
+        }
+    try:
+        return _json.loads(result.output)
+    except Exception as exc:
+        return {
+            "_error": f"non-JSON output: {exc}",
+            "_command": args,
+            "_output_head": (result.output or "")[:200],
+        }
+
+
+def _summary_field(payload: dict, *keys: str, default=None):
+    summary = payload.get("summary") or {}
+    for k in keys:
+        if k in summary and summary[k] is not None:
+            return summary[k]
+    return default
+
+
+@click.command()
+@click.option(
+    "--brief",
+    is_flag=True,
+    help="Drop per-section detail; keep only the top-level summary scores.",
+)
+@click.pass_context
+def audit(ctx, brief) -> None:
+    """One-shot AI Agent Readiness Audit.
+
+    Bundles health, debt, dead-code, risk, test-pyramid, coverage, and
+    API-surface signals into a single envelope. Designed as the
+    structured artifact a paid audit attaches to its report.
+    """
+    json_mode = ctx.obj.get("json") if ctx.obj else False
+    ensure_index()
+
+    health = _capture(["health"])
+    debt = _capture(["debt"])
+    dead = _capture(["dead"])
+    test_pyramid = _capture(["test-pyramid"])
+    api = _capture(["api", "--limit", "0"])
+    stats = _capture(["stats"])
+    hotspots = _capture(["hotspots", "--danger"])
+
+    # Top-level scores so consumers can branch fast.
+    health_score = _summary_field(health, "health_score", "score")
+    debt_total = _summary_field(debt, "total_minutes", "estimated_minutes", "total")
+    dead_count = _summary_field(dead, "dead_count", "total")
+    danger_count = _summary_field(hotspots, "count", "danger_count", default=0)
+    pyramid_total = _summary_field(test_pyramid, "total", default=0)
+    api_count = _summary_field(api, "count", default=0)
+    file_total = _summary_field(stats, "file_total", default=0)
+    sym_total = _summary_field(stats, "symbol_total", default=0)
+    coverage_pct = _summary_field(health, "imported_coverage_pct")
+
+    # Verdict — stack-rank the most pressing dimension.
+    pressures = []
+    if isinstance(health_score, (int, float)) and health_score < 60:
+        pressures.append(f"health {health_score}/100")
+    if isinstance(danger_count, int) and danger_count > 0:
+        pressures.append(f"{danger_count} danger-zone file(s)")
+    if isinstance(coverage_pct, (int, float)) and coverage_pct < 40:
+        pressures.append(f"coverage {coverage_pct:.0f}%")
+    if pressures:
+        verdict = "AUDIT — pressures: " + ", ".join(pressures)
+    else:
+        verdict = (
+            f"AUDIT — health {health_score or '?'}/100, "
+            f"{file_total} files, {sym_total} symbols, "
+            f"{api_count} public-API symbols"
+        )
+
+    summary = {
+        "verdict": verdict,
+        "health_score": health_score,
+        "debt_total": debt_total,
+        "dead_count": dead_count,
+        "danger_zone_count": danger_count,
+        "test_count": pyramid_total,
+        "api_surface": api_count,
+        "imported_coverage_pct": coverage_pct,
+        "file_total": file_total,
+        "symbol_total": sym_total,
+    }
+
+    sections = {
+        "health": health if not brief else {"summary": health.get("summary", {})},
+        "debt": debt if not brief else {"summary": debt.get("summary", {})},
+        "dead": dead if not brief else {"summary": dead.get("summary", {})},
+        "test_pyramid": test_pyramid if not brief else {"summary": test_pyramid.get("summary", {})},
+        "hotspots_danger": hotspots if not brief else {"summary": hotspots.get("summary", {})},
+        "stats": stats if not brief else {"summary": stats.get("summary", {})},
+    }
+
+    if json_mode:
+        click.echo(
+            to_json(
+                json_envelope(
+                    "audit",
+                    summary=summary,
+                    sections=sections,
+                    api_count=api_count,
+                )
+            )
+        )
+        return
+
+    click.echo(f"VERDICT: {verdict}")
+    click.echo()
+    click.echo(f"{'Metric':<28}  Value")
+    click.echo(f"{'-' * 28}  {'-' * 30}")
+    for label, value in [
+        ("health score (0-100)", health_score),
+        ("debt (total)", debt_total),
+        ("dead symbols", dead_count),
+        ("danger-zone files", danger_count),
+        ("test files indexed", pyramid_total),
+        ("public API surface", api_count),
+        ("imported coverage %", coverage_pct),
+        ("total files", file_total),
+        ("total symbols", sym_total),
+    ]:
+        click.echo(f"{label:<28}  {value}")

{roam_code-12.18 → roam_code-12.19}/src/roam/commands/cmd_complexity.py

@@ -111,11 +111,21 @@ def complexity(ctx, target, limit, threshold, by_file, bumpy_road, include_tooli
         try:
             count = conn.execute("SELECT COUNT(*) FROM symbol_metrics").fetchone()[0]
         except Exception:
-            click.echo("No complexity data found. Re-index with: roam index --force")
-            raise SystemExit(1)
-
-        if count == 0:
-            click.echo("No complexity data found. Re-index with: roam index --force")
+            count = -1
+        if count <= 0:
+            verdict = "No complexity data found. Re-index with: roam index --force"
+            if json_mode:
+                click.echo(
+                    to_json(
+                        json_envelope(
+                            "complexity",
+                            summary={"verdict": verdict, "total": 0},
+                            results=[],
+                        )
+                    )
+                )
+            else:
+                click.echo(verdict)
             raise SystemExit(1)
 
         if bumpy_road:
@@ -179,7 +189,19 @@ def complexity(ctx, target, limit, threshold, by_file, bumpy_road, include_tooli
                 sarif = complexity_to_sarif([], threshold=threshold or 0)
                 click.echo(write_sarif(sarif))
                 return
-            click.echo("No matching symbols found.")
+            verdict = "No matching symbols found."
+            if json_mode:
+                click.echo(
+                    to_json(
+                        json_envelope(
+                            "complexity",
+                            summary={"verdict": verdict, "total": 0},
+                            results=[],
+                        )
+                    )
+                )
+            else:
+                click.echo(verdict)
             return
 
         if sarif_mode:
@@ -398,7 +420,19 @@ def _bumpy_road(conn, json_mode, limit, threshold):
     ).fetchall()
 
     if not rows:
-        click.echo("No bumpy-road files found.")
+        verdict = "No bumpy-road files found."
+        if json_mode:
+            click.echo(
+                to_json(
+                    json_envelope(
+                        "complexity",
+                        summary={"verdict": verdict, "total": 0},
+                        bumpy_road=[],
+                    )
+                )
+            )
+        else:
+            click.echo(verdict)
         return
 
     if json_mode:

{roam_code-12.18 → roam_code-12.19}/src/roam/commands/cmd_config.py

@@ -543,18 +543,19 @@ def _no_mutating_options(
     exclude_pattern,
     remove_pattern,
 ) -> bool:
-    return all(
-        value is None
-        for value in (
-            db_dir,
-            use_local_cache,
-            semantic_backend,
-            onnx_model,
-            onnx_tokenizer,
-            onnx_max_length,
-            exclude_pattern,
-            remove_pattern,
-        )
+    # Pass 91 — ``use_local_cache`` is a ``is_flag=True`` Click option,
+    # so its default is ``False`` not ``None``. The previous all(... is
+    # None) check returned False even when nothing was passed, leaving
+    # ``roam config`` (no flags, no --show) silent in --json mode.
+    return (
+        db_dir is None
+        and not use_local_cache
+        and semantic_backend is None
+        and onnx_model is None
+        and onnx_tokenizer is None
+        and onnx_max_length is None
+        and exclude_pattern is None
+        and remove_pattern is None
     )