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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roam-code
-Version: 12.17
+Version: 12.18
 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 167 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 172 specialised commands are advanced surface for specialised workflows.
 
-*172 commands · 123 MCP tools · 27 languages · 100% local · zero API keys*
+*177 commands · 123 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)
@@ -83,7 +83,7 @@ Roam is a structural intelligence engine for software. It pre-indexes your codeb
 Unlike LSPs (editor-bound, language-specific) or Sourcegraph (hosted search), Roam provides architecture-level graph queries -- offline, cross-language, and compact. It goes beyond comprehension: Roam governs architecture through budget gates, simulates refactoring outcomes, orchestrates multi-agent swarms with zero-conflict guarantees, maps vulnerability reachability paths, and enables graph-level code editing without syntax errors.
 
 ```
-Codebase ──> [Index] ──> Semantic Graph ──> 155 Commands ──> AI Agent
+Codebase ──> [Index] ──> Semantic Graph ──> 177 Commands ──> AI Agent
               │              │                  │
            tree-sitter    symbols            comprehend
            27 languages   + edges            govern
@@ -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).
-- **155 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, 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.
 
 ## 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 167 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 **172 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 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.
 
 <details>
 <summary><strong>Full command reference</strong></summary>
@@ -375,6 +375,11 @@ 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 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 |
+| `roam test-impact [<range>]` | Tests transitively reachable from changed symbols (sharper scope than `affected-tests`) |
+| `roam recipes` | List every `roam ask` recipe with intent + example queries (sugar over `ask --list`) |
 
 ### Daily Workflow
 
@@ -1628,7 +1633,7 @@ roam-code/
 ├── action.yml                         # Reusable GitHub Action
 ├── src/roam/
 │   ├── __init__.py                    # Version (from pyproject.toml)
-│   ├── cli.py                         # Click CLI (155 canonical + 6 aliases)
+│   ├── cli.py                         # Click CLI (177 canonical + 7 aliases)
 │   ├── mcp_server.py                  # MCP server (122 tools, 10 resources, 5 prompts)
 │   ├── db/
 │   │   ├── connection.py              # SQLite (WAL, pragmas, batched IN)
@@ -1723,7 +1728,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: 155 canonical CLI commands and 123 MCP tools.
+- [x] Full command and MCP inventory parity in docs: 177 canonical CLI commands and 123 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.17 → roam_code-12.18}/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 167 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 172 specialised commands are advanced surface for specialised workflows.
 
-*172 commands · 123 MCP tools · 27 languages · 100% local · zero API keys*
+*177 commands · 123 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)
@@ -25,7 +25,7 @@ Roam is a structural intelligence engine for software. It pre-indexes your codeb
 Unlike LSPs (editor-bound, language-specific) or Sourcegraph (hosted search), Roam provides architecture-level graph queries -- offline, cross-language, and compact. It goes beyond comprehension: Roam governs architecture through budget gates, simulates refactoring outcomes, orchestrates multi-agent swarms with zero-conflict guarantees, maps vulnerability reachability paths, and enables graph-level code editing without syntax errors.
 
 ```
-Codebase ──> [Index] ──> Semantic Graph ──> 155 Commands ──> AI Agent
+Codebase ──> [Index] ──> Semantic Graph ──> 177 Commands ──> AI Agent
               │              │                  │
            tree-sitter    symbols            comprehend
            27 languages   + edges            govern
@@ -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).
-- **155 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, 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.
 
 ## 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 167 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 **172 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 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.
 
 <details>
 <summary><strong>Full command reference</strong></summary>
@@ -317,6 +317,11 @@ 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 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 |
+| `roam test-impact [<range>]` | Tests transitively reachable from changed symbols (sharper scope than `affected-tests`) |
+| `roam recipes` | List every `roam ask` recipe with intent + example queries (sugar over `ask --list`) |
 
 ### Daily Workflow
 
@@ -1570,7 +1575,7 @@ roam-code/
 ├── action.yml                         # Reusable GitHub Action
 ├── src/roam/
 │   ├── __init__.py                    # Version (from pyproject.toml)
-│   ├── cli.py                         # Click CLI (155 canonical + 6 aliases)
+│   ├── cli.py                         # Click CLI (177 canonical + 7 aliases)
 │   ├── mcp_server.py                  # MCP server (122 tools, 10 resources, 5 prompts)
 │   ├── db/
 │   │   ├── connection.py              # SQLite (WAL, pragmas, batched IN)
@@ -1665,7 +1670,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: 155 canonical CLI commands and 123 MCP tools.
+- [x] Full command and MCP inventory parity in docs: 177 canonical CLI commands and 123 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.17 → roam_code-12.18}/pyproject.toml

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

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

@@ -126,6 +126,11 @@ _COMMANDS = {
     "api": ("roam.commands.cmd_api", "api"),
     "exit-codes": ("roam.commands.cmd_exit_codes", "exit_codes"),
     "version": ("roam.commands.cmd_version", "version"),
+    "disambiguate": ("roam.commands.cmd_disambiguate", "disambiguate"),
+    "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"),
+    "recipes": ("roam.commands.cmd_recipes", "recipes"),
     "forecast": ("roam.commands.cmd_forecast", "forecast"),
     "plan": ("roam.commands.cmd_plan", "plan"),
     "adversarial": ("roam.commands.cmd_adversarial", "adversarial"),
@@ -237,12 +242,15 @@ _CATEGORIES = {
         "schema",
         "mcp",
         "mcp-setup",
+        "mcp-status",
         "ci-setup",
         "adrs",
         "changelog",
         "exit-codes",
         "help-search",
         "plugins",
+        "pre-commit",
+        "recipes",
         "version",
         "index-stats",
         "stats",
@@ -271,10 +279,12 @@ _CATEGORIES = {
         "critique",
         "fleet",
         "affected-tests",
+        "test-impact",
         "diagnose",
         "why-fail",
         "recommend",
         "api",
+        "disambiguate",
         "annotate",
         "annotations",
         "plan",

roam_code-12.18/src/roam/commands/cmd_disambiguate.py

@@ -0,0 +1,98 @@
+"""``roam disambiguate <name>`` — list every symbol matching this name.
+
+Pass 81 — agents calling ``roam search`` then picking the first result
+sometimes pick the wrong one when several functions share a name.
+This command shows all matches with the disambiguators (file, line,
+kind, signature, first docstring line) plus PageRank as a tiebreaker.
+"""
+
+from __future__ import annotations
+
+import click
+
+from roam.commands.resolve import ensure_index
+from roam.db.connection import open_db
+from roam.output.formatter import json_envelope, to_json
+
+
+@click.command()
+@click.argument("name")
+@click.option("--limit", type=int, default=20, show_default=True, help="Max matches to display.")
+@click.pass_context
+def disambiguate(ctx, name, limit) -> None:
+    """List every symbol matching <name> with disambiguators.
+
+    Match tiers, in order:
+      1. ``s.name = name`` (exact name match)
+      2. ``s.qualified_name = name`` (exact qname)
+      3. ``s.qualified_name LIKE '%.name'`` (suffix qname)
+    """
+    json_mode = ctx.obj.get("json") if ctx.obj else False
+    ensure_index()
+
+    with open_db(readonly=True) as conn:
+        rows = conn.execute(
+            """
+            SELECT s.id, s.name, s.qualified_name, s.kind, s.signature,
+                   s.docstring, s.line_start, f.path,
+                   COALESCE(gm.pagerank, 0) AS pagerank
+              FROM symbols s
+              JOIN files f ON f.id = s.file_id
+              LEFT JOIN graph_metrics gm ON gm.symbol_id = s.id
+             WHERE s.name = ?
+                OR s.qualified_name = ?
+                OR s.qualified_name LIKE ?
+             ORDER BY pagerank DESC, s.name
+             LIMIT ?
+            """,
+            (name, name, f"%.{name}", int(limit)),
+        ).fetchall()
+
+    matches = []
+    for r in rows:
+        doc_first = ""
+        if r["docstring"]:
+            stripped = (r["docstring"] or "").strip().splitlines()
+            doc_first = stripped[0] if stripped else ""
+        matches.append(
+            {
+                "name": r["name"],
+                "qualified_name": r["qualified_name"],
+                "kind": r["kind"],
+                "signature": (r["signature"] or "").strip(),
+                "docstring_summary": doc_first,
+                "file": r["path"],
+                "line": r["line_start"],
+                "pagerank": round(float(r["pagerank"]), 6),
+            }
+        )
+
+    verdict = (
+        f"no symbol matching '{name}'"
+        if not matches
+        else f"{len(matches)} symbol(s) matching '{name}' (top: {matches[0]['qualified_name'] or matches[0]['name']})"
+    )
+
+    if json_mode:
+        click.echo(
+            to_json(
+                json_envelope(
+                    "disambiguate",
+                    summary={"verdict": verdict, "count": len(matches)},
+                    matches=matches,
+                )
+            )
+        )
+        return
+
+    click.echo(f"VERDICT: {verdict}")
+    if not matches:
+        return
+    click.echo()
+    for m in matches:
+        ident = m["qualified_name"] or m["name"]
+        click.echo(f"  {m['kind']:<10}  {ident}  ({m['file']}:{m['line']})  PR={m['pagerank']:.5f}")
+        if m["signature"]:
+            click.echo(f"    sig: {m['signature'][:100]}")
+        if m["docstring_summary"]:
+            click.echo(f"    doc: {m['docstring_summary'][:100]}")

{roam_code-12.17 → roam_code-12.18}/src/roam/commands/cmd_map.py

@@ -42,8 +42,23 @@ def _build_symbol_entry_text(s, *, for_budget: bool = False) -> str:
 @click.option("-n", "count", default=20, help="Number of top symbols to show")
 @click.option("--full", is_flag=True, help="Show all results without truncation")
 @click.option("--budget", type=int, default=None, help="Approximate token limit for output")
+@click.option(
+    "--seed",
+    "seed_path",
+    type=str,
+    default=None,
+    help="Pass 90 — restrict the top-symbols list to symbols reachable from this file.",
+)
+@click.option(
+    "--depth",
+    "seed_depth",
+    type=int,
+    default=2,
+    show_default=True,
+    help="Pass 90 — BFS hop limit when --seed is given.",
+)
 @click.pass_context
-def map_cmd(ctx, count, full, budget):
+def map_cmd(ctx, count, full, budget, seed_path, seed_depth):
     """Show project skeleton with entry points and key symbols.
 
     Unlike ``describe`` (which generates a prose project overview), this
@@ -96,6 +111,36 @@ def map_cmd(ctx, count, full, budget):
         fetch_limit = count if budget is None else 10_000
         all_ranked = conn.execute(TOP_SYMBOLS_BY_PAGERANK, (fetch_limit,)).fetchall()
 
+        # Pass 90 — if a seed file is given, narrow ``all_ranked`` to
+        # symbols reachable from that file within ``seed_depth`` hops.
+        if seed_path:
+            try:
+                import networkx as nx
+
+                from roam.graph.builder import build_symbol_graph
+            except ImportError:
+                seed_path = None  # graph unavailable, fall through
+            if seed_path:
+                seed_norm = seed_path.replace("\\", "/")
+                seed_rows = conn.execute(
+                    "SELECT s.id FROM symbols s JOIN files f ON f.id = s.file_id "
+                    "WHERE REPLACE(f.path, '\\', '/') = ? OR REPLACE(f.path, '\\', '/') LIKE ?",
+                    (seed_norm, f"{seed_norm}%"),
+                ).fetchall()
+                seed_ids = [r["id"] for r in seed_rows]
+                if seed_ids:
+                    G = build_symbol_graph(conn)
+                    reach: set[int] = set(seed_ids)
+                    for sid in seed_ids:
+                        if sid not in G:
+                            continue
+                        try:
+                            lengths = nx.single_source_shortest_path_length(G, sid, cutoff=int(seed_depth))
+                            reach.update(lengths.keys())
+                        except Exception:
+                            continue
+                    all_ranked = [r for r in all_ranked if r["id"] in reach]
+
         # ---- Budget-aware symbol selection ----
         if budget is not None:
             # Pre-compute the preamble (stats, dirs, entries) to account

roam_code-12.18/src/roam/commands/cmd_mcp_status.py

@@ -0,0 +1,89 @@
+"""``roam mcp-status`` — health check for the MCP server.
+
+Pass 83 — companion to ``roam doctor``. Reports:
+
+  * preset (core / review / refactor / debug / architecture / full)
+  * registered tool count + core tool count
+  * backpressure limits (max_concurrent, in_flight, per-tool overrides)
+  * MCP-level result cache size + hit-rate (if anything cached this session)
+  * recent ``busy_responses_total`` count
+  * watcher status (if ROAM_MCP_WATCH=1)
+"""
+
+from __future__ import annotations
+
+import os
+
+import click
+
+from roam.output.formatter import json_envelope, to_json
+
+
+@click.command(name="mcp-status")
+@click.pass_context
+def mcp_status(ctx) -> None:
+    """Report MCP server status: preset, tools, backpressure, cache, watcher."""
+    json_mode = ctx.obj.get("json") if ctx.obj else False
+
+    preset = os.environ.get("ROAM_MCP_PRESET", "core")
+    watch_enabled = os.environ.get("ROAM_MCP_WATCH", "").strip() in {"1", "true", "yes"}
+
+    try:
+        from roam.mcp_server import _CORE_TOOLS, _REGISTERED_TOOLS, _ROAM_RESULT_CACHE
+    except Exception as exc:
+        msg = f"MCP server module unavailable: {type(exc).__name__}: {exc}"
+        if json_mode:
+            click.echo(to_json(json_envelope("mcp-status", summary={"verdict": msg, "ready": False})))
+        else:
+            click.echo(f"VERDICT: {msg}")
+        return
+
+    try:
+        from roam.mcp_extras.concurrency import metrics as concurrency_metrics
+
+        bp = concurrency_metrics()
+    except Exception:
+        bp = {"max_concurrent": None, "in_flight": None, "busy_responses_total": None, "per_tool_limits": {}}
+
+    cache_size = len(_ROAM_RESULT_CACHE)
+    registered = len(_REGISTERED_TOOLS)
+    core_count = sum(1 for n in _REGISTERED_TOOLS if n in _CORE_TOOLS)
+
+    verdict = (
+        f"MCP ready — preset={preset}, {registered} tools registered "
+        f"({core_count} core), max_concurrent={bp.get('max_concurrent')}"
+    )
+
+    if json_mode:
+        click.echo(
+            to_json(
+                json_envelope(
+                    "mcp-status",
+                    summary={
+                        "verdict": verdict,
+                        "preset": preset,
+                        "tools_registered": registered,
+                        "core_tool_count": core_count,
+                        "max_concurrent": bp.get("max_concurrent"),
+                        "in_flight": bp.get("in_flight"),
+                        "busy_responses_total": bp.get("busy_responses_total"),
+                        "cache_entries": cache_size,
+                        "watcher_enabled": watch_enabled,
+                    },
+                    backpressure=bp,
+                )
+            )
+        )
+        return
+
+    click.echo(f"VERDICT: {verdict}")
+    click.echo()
+    click.echo(f"Preset:                    {preset}")
+    click.echo(f"Tools registered:          {registered}")
+    click.echo(f"  of which core preset:    {core_count}")
+    click.echo(f"Max concurrent:            {bp.get('max_concurrent')}")
+    click.echo(f"In flight (now):           {bp.get('in_flight')}")
+    click.echo(f"Busy responses total:      {bp.get('busy_responses_total')}")
+    click.echo(f"Per-tool override count:   {len(bp.get('per_tool_limits') or {})}")
+    click.echo(f"Result-cache entries:      {cache_size}")
+    click.echo(f"Watcher enabled:           {'yes' if watch_enabled else 'no'}")

roam_code-12.18/src/roam/commands/cmd_pre_commit.py

@@ -0,0 +1,120 @@
+"""``roam pre-commit`` — install or print a git pre-commit hook.
+
+Pass 82 — generates a hook that runs ``git diff --cached | roam critique``
+on staged changes, exiting non-zero on high-severity findings. Idempotent:
+installing twice is a no-op (rewrites the same content).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from roam.commands.resolve import ensure_index
+from roam.db.connection import find_project_root
+from roam.output.formatter import json_envelope, to_json
+
+_HOOK_NAME = "pre-commit"
+_HOOK_TEMPLATE = """#!/bin/sh
+# Generated by `roam pre-commit --install`. Idempotent.
+# Runs roam critique on staged changes. Exit 5 = high-severity finding.
+# Set ROAM_PRECOMMIT_SKIP=1 to bypass.
+
+if [ "${ROAM_PRECOMMIT_SKIP:-0}" = "1" ]; then
+  exit 0
+fi
+
+if ! command -v roam >/dev/null 2>&1; then
+  echo "roam not on PATH; install with `pip install roam-code` or set ROAM_PRECOMMIT_SKIP=1." >&2
+  exit 0
+fi
+
+DIFF="$(git diff --cached)"
+if [ -z "$DIFF" ]; then
+  exit 0
+fi
+
+echo "$DIFF" | roam critique
+status=$?
+case "$status" in
+  0) exit 0 ;;
+  5) echo "roam critique flagged a high-severity finding. ROAM_PRECOMMIT_SKIP=1 to bypass." >&2 ; exit 1 ;;
+  *) echo "roam critique exited $status — not blocking. ROAM_PRECOMMIT_SKIP=1 to silence." >&2 ; exit 0 ;;
+esac
+"""
+
+
+def _hooks_dir(root: Path) -> Path:
+    return root / ".git" / "hooks"
+
+
+@click.command(name="pre-commit")
+@click.option("--install", is_flag=True, help="Write the hook into .git/hooks/pre-commit (idempotent).")
+@click.option("--print", "print_only", is_flag=True, help="Print the hook script to stdout instead of installing.")
+@click.pass_context
+def pre_commit(ctx, install, print_only) -> None:
+    """Install or preview a roam-critique pre-commit git hook."""
+    json_mode = ctx.obj.get("json") if ctx.obj else False
+    ensure_index()
+    root = find_project_root()
+    hooks = _hooks_dir(root)
+    target = hooks / _HOOK_NAME
+
+    if print_only or (not install):
+        if json_mode:
+            click.echo(
+                to_json(
+                    json_envelope(
+                        "pre-commit",
+                        summary={
+                            "verdict": "preview-only — pass --install to write the hook",
+                            "target": str(target),
+                            "exists": target.exists(),
+                        },
+                        script=_HOOK_TEMPLATE,
+                    )
+                )
+            )
+        else:
+            click.echo(f"# Would write to: {target}")
+            click.echo()
+            click.echo(_HOOK_TEMPLATE)
+            click.echo()
+            click.echo("Run `roam pre-commit --install` to write the hook.")
+        return
+
+    if not (root / ".git").exists():
+        verdict = f"no .git directory under {root} — run from inside a git repository"
+        if json_mode:
+            click.echo(to_json(json_envelope("pre-commit", summary={"verdict": verdict, "installed": False})))
+        else:
+            click.echo(f"VERDICT: {verdict}")
+        ctx.exit(2)
+        return
+
+    hooks.mkdir(parents=True, exist_ok=True)
+    existing = target.read_text(encoding="utf-8") if target.exists() else None
+    if existing == _HOOK_TEMPLATE:
+        verdict = f"hook already up to date at {target}"
+    else:
+        target.write_text(_HOOK_TEMPLATE, encoding="utf-8")
+        try:
+            # chmod +x on POSIX. On Windows the bit is ignored but harmless.
+            target.chmod(0o755)
+        except OSError:
+            pass
+        verdict = f"installed roam pre-commit hook to {target}"
+
+    if json_mode:
+        click.echo(
+            to_json(
+                json_envelope(
+                    "pre-commit",
+                    summary={"verdict": verdict, "installed": True, "target": str(target)},
+                )
+            )
+        )
+        return
+    click.echo(f"VERDICT: {verdict}")
+    click.echo("  ROAM_PRECOMMIT_SKIP=1 to bypass on a single commit.")

roam_code-12.18/src/roam/commands/cmd_recipes.py

@@ -0,0 +1,53 @@
+"""``roam recipes`` — list every ask recipe with intent + examples.
+
+Pass 88 — sugar over ``roam ask --list`` for discoverability. Useful as
+the first thing an agent runs to see what natural-language tasks
+``roam ask`` handles.
+"""
+
+from __future__ import annotations
+
+import click
+
+from roam.ask.recipes import RECIPES
+from roam.output.formatter import json_envelope, to_json
+
+
+@click.command()
+@click.pass_context
+def recipes(ctx) -> None:
+    """List every ``roam ask`` recipe with intent + example queries."""
+    json_mode = ctx.obj.get("json") if ctx.obj else False
+    items = [
+        {
+            "name": r.name,
+            "intent": r.intent,
+            "phase": r.phase,
+            "examples": list(r.examples),
+            "commands": [{"cmd": c[0], "args": list(c[1])} for c in r.commands],
+        }
+        for r in RECIPES
+    ]
+    items.sort(key=lambda x: x["name"])
+    verdict = f"{len(items)} ask recipe(s) in registry"
+
+    if json_mode:
+        click.echo(
+            to_json(
+                json_envelope(
+                    "recipes",
+                    summary={"verdict": verdict, "count": len(items)},
+                    recipes=items,
+                )
+            )
+        )
+        return
+
+    click.echo(f"VERDICT: {verdict}")
+    click.echo()
+    click.echo(f"{'Name':<26}  {'Phase':<14}  Intent")
+    click.echo(f"{'-' * 26}  {'-' * 14}  {'-' * 50}")
+    for it in items:
+        click.echo(f"{it['name']:<26}  {it['phase'][:14]:<14}  {it['intent'][:60]}")
+    click.echo()
+    click.echo('Run `roam ask "<query>"` to dispatch by intent.')