Merge origin/main into holive/improve-mcp

Resolve README.md conflict: keep 95 commands (main) + 61 MCP tools (PR).
Update comparison table tool count from 48 to 61.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: CosmoHac

README.md

@@ -4,7 +4,7 @@
 
 **The architectural intelligence layer for AI coding agents. Structural graph, architecture governance, multi-agent orchestration, vulnerability mapping, runtime analysis -- one CLI, zero API keys.**
 
-*94 commands · 26 languages · architecture OS · 100% local*
+*95 commands · 26 languages · architecture OS · 100% local*
 
 [![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)
@@ -87,7 +87,7 @@ $ roam diff                    # blast radius of uncommitted changes
 
 **Fully local.** No API keys, telemetry, or network calls. Works in air-gapped environments.
 
-**Algorithm-aware.** Built-in catalog of 23 anti-patterns. Detects suboptimal algorithms (quadratic loops, N+1 queries, unbounded recursion) and suggests fixes with Big-O improvements and confidence scores.
+**Algorithm-aware.** Built-in catalog of 23 anti-patterns. Detects suboptimal algorithms (quadratic loops, N+1 queries, unbounded recursion) and suggests fixes with Big-O improvements and confidence scores. Receiver-aware loop-invariant analysis minimizes false positives.
 
 **CI-ready.** `--json` output, `--gate` quality gates, GitHub Action, SARIF 2.1.0.
 
@@ -181,7 +181,7 @@ roam health
 
 ## Commands
 
-The [5 core commands](#core-commands) shown above cover ~80% of agent workflows. 94 commands are organized into 7 categories.
+The [5 core commands](#core-commands) shown above cover ~80% of agent workflows. 95 commands are organized into 7 categories.
 
 <details>
 <summary><strong>Full command reference</strong></summary>
@@ -198,6 +198,7 @@ The [5 core commands](#core-commands) shown above cover ~80% of agent workflows.
 | `roam minimap [--update] [-o FILE] [--init-notes]` | Compact annotated codebase snapshot for CLAUDE.md injection: stack, annotated directory tree, key symbols by PageRank, high fan-in symbols to avoid touching, hotspots, conventions. Sentinel-based in-place updates |
 | `roam config [KEY [VALUE]]` | View or set configuration options |
 | `roam map [-n N] [--full] [--budget N]` | Project skeleton: files, languages, entry points, top symbols by PageRank. `--budget` caps output to N tokens |
+| `roam schema [--diff] [--version V]` | JSON envelope schema versioning: view, diff, and validate output schemas |
 
 ### Daily Workflow
 
@@ -643,6 +644,21 @@ roam describe --agent-prompt        # compact ~500-token prompt (append to any c
 roam minimap --update               # inject/refresh annotated codebase minimap in CLAUDE.md
 ```
 
+**Agent not using Roam correctly?** If your agent is ignoring Roam and falling back to grep/read exploration, it likely doesn't have the instructions. Run:
+
+```bash
+roam describe --write          # writes instructions to your agent's config (CLAUDE.md, AGENTS.md, etc.)
+```
+
+If you already have a config file and don't want to overwrite it:
+
+```bash
+roam describe --agent-prompt   # prints a compact prompt — copy-paste into your existing config
+roam minimap --update          # injects an annotated codebase snapshot into CLAUDE.md (won't touch other content)
+```
+
+This teaches the agent which Roam command to use for each situation (e.g., `roam preflight` before changes, `roam context` for files to read, `roam diagnose` for debugging).
+
 <details>
 <summary><strong>Copy-paste agent instructions</strong></summary>
 
@@ -1160,10 +1176,13 @@ Roam is **not** a replacement for your linter, LSP, or SonarQube. It fills a dif
 |------|-------------|------------------|
 | **ctags / cscope** | Symbol index for editors | Roam adds graph metrics, git signals, architecture analysis, and AI-optimized output |
 | **LSP (pyright, gopls)** | Real-time type checking | LSP requires a running server and file:line:col queries. Roam is offline, exploratory, and cross-language |
-| **Sourcegraph** | Code search + AI | Requires hosted deployment. Roam is local-only, MIT-licensed |
-| **Aider repo map** | Tree-sitter + PageRank | Context selection for chat. Roam adds git signals, 94 architecture commands, CI gates, multi-agent orchestration |
-| **CodeScene** | Behavioral code analysis | Commercial SaaS. Roam is free, local, uses peer-reviewed algorithms (Mann-Kendall, NPMI, Personalized PageRank) |
-| **SonarQube** | Code quality + security | Heavy server. Roam's cognitive complexity follows SonarSource spec |
+| **Sourcegraph / Cody** | Code search + AI | Requires hosted deployment. Roam is local-only, MIT-licensed, zero infrastructure |
+| **Aider repo map** | Tree-sitter + PageRank | Context selection for chat. Roam adds git signals, 95 architecture commands, CI gates, multi-agent orchestration |
+| **CodeScene** | Behavioral code analysis | Commercial SaaS ($20-60k/yr). Roam is free, local, uses peer-reviewed algorithms (Mann-Kendall, NPMI, Personalized PageRank) |
+| **SonarQube** | Code quality + security | Heavy server ($15-45k/yr). Roam's cognitive complexity follows SonarSource spec |
+| **Serena MCP** | LSP-based symbol navigation | 6 MCP tools for navigation. Roam has 61 MCP tools covering architecture, governance, simulation, and orchestration |
+| **Repomix / code2prompt** | Codebase packing for LLMs | Flat file packing with no graph intelligence. Roam gives structural queries, not raw file dumps |
+| **Augment Code** | Cloud context engine | Cloud-hosted, enterprise-priced. Roam is 100% local, air-gapped, MIT-licensed |
 | **grep / ripgrep** | Text search | No semantic understanding. Can't distinguish definitions from usage |
 
 ## FAQ
@@ -1230,7 +1249,7 @@ Delete `.roam/` from your project root to clean up local data.
 git clone https://github.com/Cranot/roam-code.git
 cd roam-code
 pip install -e ".[dev]"   # includes pytest, ruff
-pytest tests/              # 2654 tests, Python 3.9-3.13
+pytest tests/              # 2656 tests, Python 3.9-3.13
 
 # Or use Make targets:
 make dev      # install with dev extras
@@ -1247,7 +1266,7 @@ roam-code/
 ├── action.yml                         # Reusable GitHub Action
 ├── src/roam/
 │   ├── __init__.py                    # Version (from pyproject.toml)
-│   ├── cli.py                         # Click CLI (94 commands, 7 categories)
+│   ├── cli.py                         # Click CLI (95 commands, 7 categories)
 │   ├── mcp_server.py                  # MCP server (61 tools, 2 resources)
 │   ├── db/
 │   │   ├── connection.py              # SQLite (WAL, pragmas, batched IN)
@@ -1360,17 +1379,25 @@ Optional: [fastmcp](https://github.com/jlowin/fastmcp) >= 2.0 (MCP server — in
 - [x] Governance DSL: `roam rules` with `.roam/rules/` YAML plugin system (v9.1)
 - [x] Topology fingerprinting: `roam fingerprint` with cross-repo comparison (v9.1)
 - [x] 30+ new commands: simulate, orchestrate, mutate, closure, adversarial, plan, invariants, bisect, intent, cut, effects, dark-matter, capsule, forecast, path-coverage, fingerprint, rules, vuln-map, vuln-reach, ingest-trace, hotspots, and more (v9.1)
+- [x] MCP lite mode: `ROAM_MCP_LITE=1` for 15 core tools (v10.0)
+- [x] YAML/HCL Tier 1 support: CI/CD pipelines, Terraform configs (v10.0)
+- [x] Compact annotated minimap for CLAUDE.md injection (v10.0)
+- [x] Algorithm detection false-positive reduction: receiver-aware loop-invariant analysis (v10.0)
 - [ ] Terminal demo GIF
 - [ ] Docker image for CI
-- [ ] VS Code extension
+- [ ] VS Code extension (CodeLens for callers/callees, inline health indicators)
+- [ ] File-system watch mode for sub-second incremental re-indexing
+- [ ] Embedding-based semantic search via local models (Ollama integration)
+- [ ] Official GitHub Action marketplace listing
+- [ ] Token budget management (`--max-tokens` flag for context-aware output)
 
 ## Contributing
 
 ```bash
 git clone https://github.com/Cranot/roam-code.git
 cd roam-code
 pip install -e .
-pytest tests/   # All 2654 tests must pass
+pytest tests/   # All 2656 tests must pass
 ```
 
 Good first contributions: add a [Tier 1 language](src/roam/languages/) (see `go_lang.py` or `php_lang.py` as templates), improve reference resolution, add benchmark repos, extend SARIF converters, add MCP tools.

benchmarks/agent-eval/compare.py

@@ -70,9 +70,10 @@ def print_task_table(task: str, lookup: dict):
     print(f"{'=' * 80}")
 
     # Header
-    header = f"{'Agent':<14} {'Mode':<10}"
+    header_parts = [f"{'Agent':<14} {'Mode':<10}"]
     for _, label, _, _ in SCORE_COLUMNS:
-        header += f" {label:>8}"
+        header_parts.append(f" {label:>8}")
+    header = "".join(header_parts)
     print(header)
     print("-" * len(header))
 
@@ -83,19 +84,19 @@ def print_task_table(task: str, lookup: dict):
             if not scores:
                 continue
 
-            row = f"{agent:<14} {mode:<10}"
+            row_parts = [f"{agent:<14} {mode:<10}"]
             for field, _, fmt, _ in SCORE_COLUMNS:
                 val = scores.get(field)
                 if val is None:
-                    row += f" {'N/A':>8}"
+                    row_parts.append(f" {'N/A':>8}")
                 elif isinstance(val, bool):
-                    row += f" {'PASS' if val else 'FAIL':>8}"
+                    row_parts.append(f" {'PASS' if val else 'FAIL':>8}")
                 else:
                     try:
-                        row += f" {fmt.format(val):>8}"
+                        row_parts.append(f" {fmt.format(val):>8}")
                     except (ValueError, TypeError):
-                        row += f" {str(val)[:8]:>8}"
-            print(row)
+                        row_parts.append(f" {str(val)[:8]:>8}")
+            print("".join(row_parts))
 
 
 def print_agent_summary(agent: str, lookup: dict):

src/roam/catalog/detectors.py

@@ -822,9 +822,29 @@ def detect_loop_invariant_call(conn):
 
     # Calls that are intentionally per-iteration (suppress)
     _INTENTIONAL_CALLS = {
+        # Logging / output
         "print", "log", "debug", "info", "warn", "warning", "error",
+        # Collection mutation
         "append", "add", "push", "extend", "write", "send",
+        "get", "values", "items", "keys", "update", "pop", "remove",
+        "insert", "setdefault", "discard",
+        # String methods (inherently per-item)
+        "startswith", "endswith", "replace", "format", "strip", "split",
+        "join", "lower", "upper", "lstrip", "rstrip", "encode", "decode",
+        "ljust", "rjust", "center", "zfill",
+        # Event / tracking
         "emit", "track", "record", "increment", "decrement",
+        # Iteration helpers / builtins
+        "enumerate", "zip", "range", "sorted", "reversed",
+        "list", "dict", "set", "tuple", "len", "str", "int", "float",
+        "bool", "bytes", "type",
+        # Math / comparison builtins (per-item reductions)
+        "max", "min", "sum", "abs", "round", "pow",
+        "isinstance", "issubclass", "hasattr", "getattr", "setattr",
+        # File / IO
+        "resolve", "execute", "fetchone", "fetchall", "read_text",
+        "read_bytes", "open",
+        # Control flow
         "sleep", "yield",
     }
 

src/roam/commands/cmd_orphan_routes.py

@@ -360,6 +360,12 @@ def _determine_confidence(classified: dict) -> str:
 # Controller method analysis
 # ---------------------------------------------------------------------------
 
+_RE_PUBLIC_METHOD = re.compile(
+    r"public\s+function\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(",
+    re.IGNORECASE,
+)
+
+
 def _extract_controller_public_methods(project_root: Path,
                                        controller_name: str) -> list[str]:
     """Find public methods in a controller PHP file.
@@ -383,12 +389,7 @@ def _extract_controller_public_methods(project_root: Path,
         except OSError:
             continue
 
-        # Extract public function names
-        method_re = re.compile(
-            r"public\s+function\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(",
-            re.IGNORECASE,
-        )
-        methods = method_re.findall(source)
+        methods = _RE_PUBLIC_METHOD.findall(source)
         # Filter out magic methods
         return [m for m in methods if not m.startswith("__")]
 

src/roam/index/complexity.py

@@ -693,17 +693,13 @@ def _extract_loop_vars(loop_node, source: bytes) -> set[str]:
 
 
 def _call_uses_loop_vars(call_node, source: bytes, loop_vars: set[str]) -> bool:
-    """Check if any argument of a call expression references a loop variable."""
-    # Find argument list node
-    args_node = None
-    for child in call_node.children:
-        if child.type in ("argument_list", "arguments", "template_string"):
-            args_node = child
-            break
-    if args_node is None:
-        return False
+    """Check if a call expression depends on a loop variable.
+
+    Checks both arguments AND the call receiver (the object before ``.method()``).
+    For example, ``loop_var.method()`` and ``dict[loop_var].call()`` are both
+    loop-dependent even if the argument list is empty or constant.
+    """
 
-    # Walk all identifiers in the arguments
     def _has_loop_var(node) -> bool:
         if node.type == "identifier":
             name = source[node.start_byte:node.end_byte].decode(
@@ -715,7 +711,32 @@ def _has_loop_var(node) -> bool:
                 return True
         return False
 
-    return _has_loop_var(args_node)
+    # Check the call receiver (object before .method())
+    for child in call_node.children:
+        if child.type in ("member_expression", "attribute",
+                          "field_expression"):
+            # Check the object part (everything except the method name)
+            for sub in child.children:
+                if sub.type not in ("identifier", "property_identifier",
+                                    "field_identifier", "."):
+                    if _has_loop_var(sub):
+                        return True
+            # Also check if the direct object identifier is a loop var
+            for sub in child.children:
+                if sub.type == "identifier":
+                    name = source[sub.start_byte:sub.end_byte].decode(
+                        "utf-8", errors="replace")
+                    if name in loop_vars:
+                        return True
+                break  # only check the first identifier (the object)
+
+    # Check argument list
+    for child in call_node.children:
+        if child.type in ("argument_list", "arguments", "template_string"):
+            if _has_loop_var(child):
+                return True
+
+    return False
 
 
 def _is_bounded_loop(loop_node, source: bytes) -> bool:

src/roam/rules/engine.py

@@ -165,33 +165,34 @@ def _matches_glob(file_path: str, pattern: str) -> bool:
         return fnmatch.fnmatch(norm, pat)
 
     # Convert glob pattern with ** to regex
-    regex = ""
+    parts: list[str] = []
     i = 0
     while i < len(pat):
         c = pat[i]
         if c == "*":
             if i + 1 < len(pat) and pat[i + 1] == "*":
                 if i + 2 < len(pat) and pat[i + 2] == "/":
-                    regex += "(?:.+/)?"
+                    parts.append("(?:.+/)?")
                     i += 3
                     continue
                 else:
-                    regex += ".*"
+                    parts.append(".*")
                     i += 2
                     continue
             else:
-                regex += "[^/]*"
+                parts.append("[^/]*")
                 i += 1
         elif c == "?":
-            regex += "[^/]"
+            parts.append("[^/]")
             i += 1
         elif c in r".+^${}()|[]":
-            regex += "\\" + c
+            parts.append("\\" + c)
             i += 1
         else:
-            regex += c
+            parts.append(c)
             i += 1
 
+    regex = "".join(parts)
     return re.match("^" + regex + "$", norm) is not None