PyPI - roam-code - Versions diffs - 12.46__tar.gz → 12.50__tar.gz - Mend

roam-code 12.46tar.gz → 12.50tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (682) hide show

{roam_code-12.46 → roam_code-12.50}/LICENSE RENAMED Viewed

@@ -1,3 +1,4 @@
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -137,8 +138,8 @@
    6. Trademarks. This License does not grant permission to use the trade
       names, trademarks, service marks, or product names of the Licensor,
-      except as required for describing the origin of the Work and
-      reproducing the content of the NOTICE file.
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
    7. Disclaimer of Warranty. Unless required by applicable law or
       agreed to in writing, Licensor provides the Work (and each
@@ -162,15 +163,16 @@
       other commercial damages or losses), even if such Contributor
       has been advised of the possibility of such damages.
-   9. Accepting Warranty or Support. While redistributing the Work or
-      Derivative Works thereof, You may accept warranty or support,
-      indemnity, or other liability obligations and/or rights consistent
-      with this License. However, in accepting such obligations, You may
-      act only on Your own behalf and on Your sole responsibility, not on
-      behalf of any other Contributor, and only if You agree to indemnify,
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
       defend, and hold each Contributor harmless for any liability
       incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or support.
+      of your accepting any such warranty or additional liability.
    END OF TERMS AND CONDITIONS
@@ -185,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
-   Copyright 2025-2026 CosmoHac
+   Copyright [yyyy] [name of copyright owner]
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -195,6 +197,6 @@
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-   implied. See the License for the specific language governing permissions and
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
    limitations under the License.

{roam_code-12.46 → roam_code-12.50}/PKG-INFO RENAMED Viewed

@@ -1,14 +1,16 @@
 Metadata-Version: 2.4
 Name: roam-code
-Version: 12.46
+Version: 12.50
 Summary: Instant codebase comprehension for AI coding agents
-Author: CosmoHac
+Author: Cranot
 License-Expression: Apache-2.0
-Project-URL: Homepage, https://github.com/Cranot/roam-code
-Project-URL: Documentation, https://cranot.github.io/roam-code/
+Project-URL: Homepage, https://roam-code.com/
+Project-URL: Documentation, https://roam-code.com/docs/
 Project-URL: Repository, https://github.com/Cranot/roam-code
 Project-URL: Issues, https://github.com/Cranot/roam-code/issues
 Project-URL: Changelog, https://github.com/Cranot/roam-code/blob/main/CHANGELOG.md
+Project-URL: Pricing, https://roam-code.com/pricing
+Project-URL: Security, https://roam-code.com/security
 Keywords: code-intelligence,static-analysis,mcp-server,tree-sitter,architecture,code-graph,ai-coding,graph-analysis,code-quality,cli,codebase,code-analysis,ai-tools,mcp,sql
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
@@ -64,9 +66,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 188 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 200 specialised commands are advanced surface for specialised workflows.
-*193 commands · 136 MCP tools · 27 languages · 100% local · zero API keys*
+*205 commands · 137 MCP tools · 28 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)
@@ -78,19 +80,37 @@ A local code graph (SQLite + tree-sitter + git history) that gives any agent —
 ---
+### Killer use case: post-rename doc hygiene
+```bash
+git mv docs/old-guide.md docs/new-guide.md
+roam stale-refs --fix preview     # see what auto-rewrites are safe
+roam stale-refs --fix apply       # rewrite README + CHANGELOG + everywhere
+```
+`stale-refs` finds every dangling markdown link, HTML href, backtick path, and
+broken `#anchor` across the repo, with confidence-tagged rename hints from git
+history + basename match + LLM enrichment. Composable with `--gate` (CI),
+`--diff` (branch-only), `--baseline-from` (acknowledged debt), `--watch` (live),
+`--check-external` (HTTP validation), `--sarif` (Code Scanning), and a
+companion `roam lsp` server for editor squiggles. See
+[stale-refs in the command table](#commands).
+---
 ## What is Roam?
 Roam is a structural intelligence engine for software. It pre-indexes your codebase into a semantic graph -- symbols, dependencies, call graphs, architecture layers, git history, and runtime traces -- stored in a local SQLite DB. Agents query it via CLI or MCP instead of repeatedly grepping files and guessing structure.
-> **For teams running AI coding agents:** Roam ships two paid layers on top of the free CLI — **[Roam Agent Review](#roam-agent-review-pr-bot-for-ai-generated-changes)** (PR bot scoring AI-generated changes for structural risk) and **[Roam Cloud Lite](#roam-cloud-lite-metrics-history-no-source-upload)** (metrics-history dashboard, no source code upload). Both run on the OSS engine and are licenced separately.
+> **For teams running AI coding agents:** Roam ships two paid layers on top of the free CLI — **[Roam Review](#roam-review-pr-bot-for-ai-generated-changes)** (PR bot scoring AI-generated changes for structural risk) and **[Roam Cloud](#roam-cloud-metrics-history-no-source-upload)** (metrics-history dashboard, no source-code bodies uploaded). Both run on the OSS engine and are licensed separately.
 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 ──> 177 Commands ──> AI Agent
+Codebase ──> [Index] ──> Semantic Graph ──> 194 Commands ──> AI Agent
               │              │                  │
            tree-sitter    symbols            comprehend
-           27 languages   + edges            govern
+           28 languages   + edges            govern
            git history    + metrics          refactor
            runtime traces + architecture     orchestrate
 ```
@@ -160,7 +180,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, 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.
+- **205 CLI commands, 137 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
@@ -172,7 +192,7 @@ $ roam diff                    # blast radius of uncommitted changes
 ### v11.1.2 -- SQL + Scala Tier 1, 27 Languages
 - **SQL DDL promoted to Tier 1** with dedicated `SqlExtractor` -- tables, columns, views, functions, triggers, schemas, types (enums), sequences, ALTER TABLE ADD COLUMN. Foreign keys produce graph edges; views and triggers reference source tables. Database-schema projects now work with `roam health`, `roam layers`, `roam impact`, `roam coupling` and all graph commands.
 - **Scala promoted to Tier 1** with dedicated `ScalaExtractor` -- classes, traits, objects, case classes, sealed hierarchies, val/var properties, type aliases, imports, and inheritance. Full `extends` + `with` trait mixin resolution.
-- **27 languages** with 16 dedicated Tier 1 extractors.
+- **28 languages** with 17 dedicated Tier 1 extractors.
 - `server.json` for official MCP Registry submission.
 ### v11.1.1 -- Command Quality Audit
@@ -296,10 +316,10 @@ First index takes ~5s for 200 files, ~15s for 1,000 files. Subsequent runs are i
 - **Set up your AI agent:** `roam describe --write` (auto-detects CLAUDE.md, AGENTS.md, .cursor/rules, etc. — see [integration instructions](#integration-with-ai-coding-tools))
 - **Explore:** `roam health` → `roam weather` → `roam map`
-- **Run the v2 stack on every PR:** `git diff | roam pr-analyze --explain` (gates AI-generated risk; pair with `roam pr-comment-render` for sticky GitHub comments — see [Roam Agent Review](#roam-agent-review-pr-bot-for-ai-generated-risk))
-- **First-touch demo:** `roam dogfood` (audit + pr-analyze + audit-trail + EU AI Act conformance in one envelope)
+- **Run the v2 stack on every PR:** `git diff | roam pr-analyze --explain` (gates AI-generated risk; pair with `roam pr-comment-render` for sticky GitHub comments — see [Roam Review](#roam-review-pr-bot-for-ai-generated-changes))
+- **First-touch demo:** `roam dogfood` (audit + pr-analyze + audit-trail + governance checks in one envelope)
 - **Add to CI:** `roam init` already generated a GitHub Action
-- **Customer-facing artifacts:** see [`templates/`](templates/) — starter rule packs (Python / TypeScript / Go / Java / Kotlin / Rust at [`templates/rules/`](templates/rules/)), audit-report template ([`templates/audit-report/`](templates/audit-report/)), legal templates ([`templates/legal/`](templates/legal/)), v2 product specs ([`templates/products/`](templates/products/))
+- **Customer-facing artifacts:** see starter rule packs at [`templates/rules/`](templates/rules/), the audit-report template + redacted sample at [`templates/audit-report/`](templates/audit-report/), and the security/procurement packet at [`templates/legal/security-procurement-packet.md`](templates/legal/security-procurement-packet.md).
 <details>
 <summary><strong>Try it on Roam itself</strong></summary>
@@ -334,7 +354,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 188 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 **193 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 ~200 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 **205 commands organised into 7 categories** (plus 7 aliases for muscle memory: `algo` → `math`, `weather` → `churn`, `digest` / `snapshot` / `trend` → `trends`, `onboard` → `understand`, `refs` → `uses`), but you don't need to know that to start.
 <details>
 <summary><strong>Full command reference</strong></summary>
@@ -376,28 +396,31 @@ roam health
 | `roam stats` | Aggregate metrics over the index: count by language, file role, kind, plus recent commit activity |
 | `roam timeline <symbol>` | Chronological commits that touched the file owning the symbol — author, date, lines added/removed |
 | `roam pr-prep [<range>]` | One-shot pre-PR fitness check that bundles diff + critique + pr-risk into one envelope |
-| `roam pr-analyze [<range>] [--input F] [--rules F] [--gate]` | Agent-aware PR risk verdict: aggregates `pr-prep` with AI-likelihood scoring, `.roam/rules.yml` enforcement, and INTENTIONAL/SAFE/REVIEW/BLOCK mapping; CI gate via `--gate` (exit 5 on BLOCK); EU AI Act Article 12 audit trail via `--audit-trail` |
+| `roam pr-analyze [<range>] [--input F] [--rules F] [--gate]` | Agent-aware PR risk verdict: aggregates `pr-prep` with AI-likelihood scoring, `.roam/rules.yml` enforcement, and INTENTIONAL/SAFE/REVIEW/BLOCK mapping; CI gate via `--gate` (exit 5 on BLOCK); governance audit trail via `--audit-trail` |
 | `roam pr-comment-render --input F` | Render a markdown PR comment from a `pr-analyze` JSON envelope; styles: `github`, `gitlab`, `plain` |
-| `roam metrics-push [--token T] [--anonymize] [--dry-run]` | Push metrics-only summary (no source code) from `roam audit` to a Roam Cloud Lite endpoint; `--dry-run` prints the payload locally |
+| `roam pr-replay [<sha>] [--audit-trail]` | Replay a PR's analysis at a specific commit (or HEAD); useful for reproducing audit decisions and validating cache stability |
+| `roam metrics-push [--token T] [--anonymize] [--dry-run]` | Push metrics-only summary (no source-code bodies) from `roam audit` to a Roam Cloud endpoint; `--dry-run` prints the payload locally |
 | `roam audit-trail-verify [--input F] [--gate]` | Walk the EU AI Act audit-trail JSONL and verify SHA-256 chain integrity; exit 5 on broken chain |
 | `roam audit-trail-export [--format md\|json\|csv] [--since T] [--verdict V] [--aggregate]` | Export the audit trail for procurement / compliance review; `--aggregate` rolls up per actor / repo / verdict / month |
-| `roam audit-trail-conformance-check [--retention-days N] [--gate]` | Score the audit trail against an EU AI Act Article 12 checklist (chain integrity, timestamps, actors, reproducibility, retention) |
-| `roam article-12-check [--output F] [--pdf F]` | EU AI Act Article 12 readiness assessment; 6-item checklist → 1-page Markdown / PDF report. Captures Article-12-curious leads (Aug 2 2026 deadline). |
+| `roam audit-trail-conformance-check [--retention-days N] [--gate]` | Score the audit trail against governance-evidence checks (chain integrity, timestamps, actors, reproducibility, retention) |
+| `roam article-12-check [--output F] [--pdf F]` | Article 12 scope/readiness assessment for actual Annex III high-risk AI-system buyers; produces a 1-page Markdown / PDF report. |
 | `roam capabilities [--emit yaml\|json\|text] [--category X] [--ai-safe-only]` | Emit the decorator-driven capability registry — every command's machine-readable shape (inputs, outputs, ai_safe flag, since-version). For Roam Review GitHub App + MCP filtering. |
 | `roam skill-generate [--target claude\|cursor\|continue\|aider] [--output F]` | Generate an agent-runtime skill manifest from the capability registry. SKILL.md / .mdc / config snippets — derived from decorators, never hand-edited. |
 | `roam compare <baseline.db> <target.db> [--top N] [--threshold N]` | Structural delta between two indices: symbols added/removed/moved + per-file complexity deltas + IMPROVED/SIDEWAYS/REGRESSED verdict. The "did this refactor actually work?" tool. |
+| `roam migration-plan [--target spec.yml] [--move SYMBOL=path] [--max-risk low\|medium\|high]` | Generate an ordered migration plan from current state to a target architecture. Each step annotated with blast-radius (caller count) + risk score (low/medium/high) + cross-layer detection. |
 | `roam permit [--staged] [--input F] [--symbol N]` | Structural-permission verdict facade for AI agents: ALLOW/REVIEW/BLOCK over critique + preflight + blast-radius. Exit codes 0/5/6 for Cursor rules / Claude Code hooks / pre-commit / CI gates. |
 | `roam postmortem <commit-range> [--limit N] [--show N]` | Replay current detectors against past commits; reports findings that would have surfaced pre-merge. The "would Roam have caught my Q1 incident?" demo. |
 | `roam rules-validate [PATH] [--against DIFF] [--strict] [--gate] [--explain]` | Lint a `.roam/rules.yml` for typos, schema mistakes, unknown patterns, duplicate IDs; optional dry-run against a sample diff |
-| `roam dogfood [--no-audit] [--no-pr-analyze] [--no-audit-trail]` | One-shot v2 stack runner: audit + pr-analyze + audit-trail + Article 12 conformance — first-touch demo for any repo |
+| `roam dogfood [--no-audit] [--no-pr-analyze] [--no-audit-trail]` | One-shot v2 stack runner: audit + pr-analyze + audit-trail + governance checks — first-touch demo for any repo |
 | `roam suppress <finding-id> --reason "…"` | Suppress a math / over-fetch / missing-index / auth-gaps false positive with audit-trail-friendly record (`.roam/suppressions.json`); `--list` / `--remove` complete the workflow |
 | `roam why-fail <test>` | Find recently-changed symbols transitively reachable from a failing test |
+| `roam why-slow <symbol>` | Surface runtime hotspots and slow callers for a specific symbol (uses runtime traces if present) |
 | `roam recommend <symbol>` | Surface related symbols using call-graph + co-change + clone signals |
 | `roam graph-stats` | Graph-level invariants: density, weak components, non-trivial cycles, top inbound symbols |
 | `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 audit [--brief]` | One-shot AI-governance audit envelope — 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 |
@@ -415,7 +438,7 @@ roam health
 | `roam retrieve <task> [--budget N] [--k N] [--seed-files PATH]` | Graph-aware context for free-form tasks: FTS5 + structural rerank (PageRank + clones) + token budget |
 | `roam critique [--input DIFF] [--intent TEXT] [--high-callers N]` | Verify a patch against the graph: clones-not-edited + blast radius + intent-vs-semantic-diff. Pipe `git diff` in. Exit 5 on high severity. |
 | `roam fleet plan <goal> [--n-agents N] [--adapter raw\|composio\|copilot]` | Graph-aware planner: Louvain partition + co-change + PageRank anchors → `.roam-fleet.json` for Composio/Copilot CLI/raw. |
-| `roam ask <query> [--list] [--explain] [--recipe NAME]` | One-phrase intent classifier over a 24-recipe registry with phase, review-lens, gate, and follow-up metadata — composes preflight/retrieve/critique/fleet/understand/diagnose/trace/trends/hotspots/debt/taint/dead/coupling to cover the most common workflows. |
+| `roam ask <query> [--list] [--explain] [--recipe NAME]` | One-phrase intent classifier over a 25-recipe registry with phase, review-lens, gate, and follow-up metadata — composes preflight/retrieve/critique/fleet/understand/diagnose/trace/trends/hotspots/debt/taint/dead/coupling/stale-refs to cover the most common workflows. |
 | `roam workflow [RECIPE] [--list] [--query TEXT]` | Inspect a recipe DAG, review lenses, gates, rendered command arguments, and follow-up commands without running the workflow. |
 | `roam taint [--rules-dir PATH] [--rule NAME] [--rules-pack PACK] [--ci]` | Graph-reach taint analysis with OpenVEX-correct VEX justifications. YAML rule packs (10 starter packs: sqli, xss, ssrf, path-traversal, command-injection, deserialization, open-redirect, urllib, socketio, fileupload). |
 | `roam cga emit [--include-taint] [--sign --key]` | Code Graph Attestation — in-toto v1 statement with `roam-code.dev/CodeGraph/v1` predicate, Merkle root + edge bundle digest. `--include-taint` embeds OpenVEX-shaped reachability claims from `roam taint`. `--sign` signs with cosign (graceful skip if absent); `roam cga verify` round-trips both predicate digest and cosign signature. |
@@ -591,7 +614,7 @@ src/
       formatter.py            # to_json, json_envelope
     cli.py                    # cli, LazyGroup
     mcp_server.py
-tests/  (186 files)
+tests/  (267 files)
 ` ` `
 **Key symbols** (PageRank): `open_db` · `ensure_index` · `json_envelope` · `to_json` · `LanguageExtractor`
@@ -660,6 +683,8 @@ The sentinel pair `<!-- roam:minimap -->` / `<!-- /roam:minimap -->` is replaced
 | `roam bus-factor [--brain-methods]` | Knowledge loss risk per module |
 | `roam doc-staleness` | Detect stale docstrings |
 | `roam docs-coverage` | Public-symbol doc coverage + stale docs + PageRank-ranked missing-doc hotlist |
+| `roam stale-refs [--gate] [--diff REF] [--fix preview\|apply]` | Find dangling file references AND markdown anchor mismatches — confidence-tagged rename hints from git history / basename / symbol graph; HIGH-confidence auto-fix; branch-diff filter for CI; SARIF export. Index-free. |
+| `roam lsp` | Minimal LSP server (JSON-RPC over stdio). Wire into VS Code / Neovim / JetBrains as a custom server to get squiggly underlines on dangling links and missing anchors as you type. |
 | `roam suggest-refactoring [--limit N] [--min-score N]` | Proactive refactoring recommendations ranked by complexity, coupling, churn, smells, coverage gaps, and debt |
 | `roam plan-refactor <symbol> [--operation auto\|extract\|move]` | Ordered refactor plan with blast radius, test gaps, layer risk, and simulation-based strategy preview |
 | `roam test-scaffold <name\|file> [--write] [--framework F]` | Generate test file/function/import skeletons from symbol data (pytest, jest, Go, JUnit, RSpec) |
@@ -984,7 +1009,7 @@ pip install "roam-code[mcp]"
 roam mcp
 ```
-103 tools, 10 resources, and 5 prompts are available in the full preset. Most tools are read-only index queries; side-effect tools are explicitly annotated.
+137 tools, 10 resources, and 5 prompts are available in the full preset. Most tools are read-only index queries; side-effect tools are explicitly annotated.
 **MCP v2 highlights (v11):**
 - In-process MCP execution (no subprocess shell-out per call)
@@ -1015,9 +1040,9 @@ 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 136)</strong></summary>
+<summary><strong>MCP tool list (all 137)</strong></summary>
-*New in v12.26: `roam_pr_analyze`, `roam_pr_comment_render`, `roam_metrics_push`, `roam_audit_trail_verify`, `roam_audit_trail_export`, `roam_audit_trail_conformance_check`, `roam_rules_validate`, `roam_dogfood` — Roam Agent Review + Cloud Lite engines + EU AI Act audit-trail toolkit + production-grade rules linting + one-shot v2 stack runner.*
+*New in v12.26: `roam_pr_analyze`, `roam_pr_comment_render`, `roam_metrics_push`, `roam_audit_trail_verify`, `roam_audit_trail_export`, `roam_audit_trail_conformance_check`, `roam_rules_validate`, `roam_dogfood` — Roam Review + Cloud engines + governance audit-trail toolkit + production-grade rules linting + one-shot v2 stack runner.*
 | Tool | Description |
 |------|-------------|
@@ -1037,7 +1062,7 @@ Core preset tools: `roam_affected_tests`, `roam_batch_get`, `roam_batch_search`,
 | `roam_oracle_is_test_only` | Boolean oracle: are ALL callers of this symbol in test files? |
 | `roam_oracle_is_reachable_from_entry` | Boolean oracle: can BFS reach this symbol from any entry-point? |
 | `roam_oracle_is_clone_of` | Boolean oracle: does this symbol participate in a persisted clone cluster? |
-| `roam_oracle_test_only` | Alias of `roam_oracle_is_test_only` (round 4 #15 — accept the shorter name) |
+| `roam_oracle_test_only` | Alias of `roam_oracle_is_test_only` (shorter name) |
 | `roam_oracle_batch` | Run multiple oracle queries in one call (tri-state envelopes per result) |
 | `roam_taint_classify` | LLM-augmented taint classification (IDOR/AUTHZ/SQLI/...) via MCP sampling |
 | `roam_taint` | Static taint analysis — graph-reach BFS with OpenVEX-correct findings |
@@ -1050,10 +1075,10 @@ Core preset tools: `roam_affected_tests`, `roam_batch_get`, `roam_batch_search`,
 | `roam_pr_risk` | Risk score for pending changes |
 | `roam_pr_analyze` | Agent-aware PR verdict: pr-prep + AI-likelihood + `.roam/rules.yml` + INTENTIONAL/SAFE/REVIEW/BLOCK |
 | `roam_pr_comment_render` | Render a markdown PR comment from a `roam_pr_analyze` envelope |
-| `roam_metrics_push` | Push metrics-only summary (no source code) to Roam Cloud Lite; default dry-run |
+| `roam_metrics_push` | Push metrics-only summary (no source-code bodies) to Roam Cloud; default dry-run |
 | `roam_audit_trail_verify` | Verify SHA-256 chain integrity of an EU AI Act audit-trail JSONL |
 | `roam_audit_trail_export` | Export the audit trail as markdown / json / csv (with date / verdict filters) for procurement |
-| `roam_audit_trail_conformance_check` | Score the audit trail against an EU AI Act Article 12 checklist (chain / timestamps / actors / reproducibility / retention) |
+| `roam_audit_trail_conformance_check` | Score the audit trail against governance-evidence checks (chain / timestamps / actors / reproducibility / retention) |
 | `roam_rules_validate` | Lint a `.roam/rules.yml` for typos, schema mistakes, unknown patterns, duplicate IDs |
 | `roam_dogfood` | One-shot v2 stack runner — audit + pr-analyze + audit-trail + conformance in one envelope |
 | `roam_breaking_changes` | Detect breaking changes between refs |
@@ -1108,6 +1133,7 @@ Core preset tools: `roam_affected_tests`, `roam_batch_get`, `roam_batch_search`,
 | `roam_weather` | Code hotspots: churn x complexity ranking |
 | `roam_debt` | Hotspot-weighted technical debt prioritization with optional ROI estimate |
 | `roam_docs_coverage` | Doc coverage and stale-doc drift with PageRank-ranked missing docs |
+| `roam_stale_refs` | Find dangling file references — markdown links / HTML href-src / backtick paths whose target is missing |
 | `roam_suggest_refactoring` | Rank proactive refactoring candidates using complexity, coupling, churn, smells, and coverage gaps |
 | `roam_plan_refactor` | Build an ordered refactor plan for one symbol with risk/test/simulation context |
 | `roam_n1` | Detect N+1 I/O patterns in ORM code |
@@ -1240,11 +1266,11 @@ Add to `.vscode/mcp.json`:
 </details>
-## Roam Agent Review (PR bot for AI-generated changes)
+## Roam Review (PR bot for AI-generated changes)
-Most "AI safety net" tools — CodeRabbit, Greptile, Qodo — review PR **semantics** (does the diff *look* right?). They don't read your **graph**: who calls the changed symbol, which layer it belongs to, whether the AI just touched a god-component with 47 callers. Roam Agent Review fills that gap.
+Most "AI safety net" tools — CodeRabbit, Greptile, Qodo — review PR **semantics** (does the diff *look* right?). They don't read your **graph**: who calls the changed symbol, which layer it belongs to, whether the AI just touched a god-component with 47 callers. Roam Review fills that gap.
-`roam pr-analyze` is the CLI engine: pipe a unified diff in, get back a verdict (`INTENTIONAL` / `SAFE` / `REVIEW` / `BLOCK`) plus AI-likelihood score, blast radius, rule violations, suggested reviewers, and an EU AI Act Article 12 audit-trail record.
+`roam pr-analyze` is the CLI engine: pipe a unified diff in, get back a verdict (`INTENTIONAL` / `SAFE` / `REVIEW` / `BLOCK`) plus AI-likelihood score, blast radius, rule violations, suggested reviewers, and a governance audit-trail record.
 ```bash
 git diff main..HEAD | roam pr-analyze --explain --with-reviewers --audit-trail
@@ -1252,7 +1278,7 @@ roam pr-analyze main..HEAD --gate                      # exit 5 on BLOCK (CI gat
 roam --json pr-analyze --input pr.diff | roam pr-comment-render   # ready-to-post markdown
 roam pr-analyze --batch ./diffs/ --cache --parallel 4  # 24-55x speedup on incremental re-runs
 roam audit-trail-verify                                # check SHA-256 chain integrity
-roam audit-trail-conformance-check --gate              # EU AI Act Article 12 score (CI)
+roam audit-trail-conformance-check --gate              # governance-evidence score (CI)
 ```
 **Nine weighted heuristic signals** score the diff for AI-likelihood: add/remove ratio, comment density, test coverage, function-size variance, generic naming, orphan imports, **placeholder density** (TODO/FIXME/NotImplementedError stubs), **LLM-phrase density** ("we use this approach because…"), **suspicious imports** (numbered modules, mass typing imports). Each carries **language-aware weights** across Python / TypeScript / JavaScript / Go / Rust / Java / Kotlin. Starter rule packs ship for Python, TypeScript, Go, and Java at [`templates/rules/`](templates/rules/) — drop one at `.roam/rules.yml` to enable. Custom rules look like:
@@ -1274,13 +1300,13 @@ rules:
 A **drift baseline** (`--save-baseline` / `--baseline FILE`) compares the current PR's signals against the previous analysis and auto-escalates the verdict on regression — the GitHub App reads this to render `(+5 vs prev)` / `(-22 vs prev)` arrows on every push.
-The **`pr-analyze --audit-trail`** flag appends a SHA-256-chained record to `.roam/audit-trail.jsonl` for each analysis (actor, repo, git SHA, diff hash, verdict, blast radius, AI-likelihood, intent marker). `roam audit-trail-verify` walks the chain and surfaces tampered records; `roam audit-trail-export --format md|csv|json` produces procurement-friendly reports. Built for **EU AI Act Article 12** compliance ahead of the August 2 2026 enforcement deadline.
+The **`pr-analyze --audit-trail`** flag appends a SHA-256-chained record to `.roam/audit-trail.jsonl` for each analysis (actor, repo, git SHA, diff hash, verdict, blast radius, AI-likelihood, intent marker). `roam audit-trail-verify` walks the chain and surfaces tampered records; `roam audit-trail-export --format md|csv|json` produces procurement-friendly reports. This is best framed as SOC 2 CC8.1, ISO 42001, and internal AI-governance evidence. Article 12 is only relevant for actual Annex III high-risk AI-system buyers, and Roam's records are supporting evidence rather than complete runtime inference logs.
 A hosted GitHub App is in development on top of this CLI engine. Until it ships, the CLI is usable today as a free CI gate (`roam pr-analyze --gate` exits 5 on BLOCK).
-## Roam Cloud Lite (metrics history, no source upload)
+## Roam Cloud (metrics history, no source upload)
-`roam metrics-push` sends a *summary-only* payload from `roam audit --json` to a Roam Cloud Lite endpoint — numerical metrics, file paths (or SHA-256 hashes when `--anonymize`), and identifier names only. **No source-code bodies are transmitted**, ever. Inspect the exact payload locally with `--dry-run` before any token is set.
+`roam metrics-push` sends a *summary-only* payload from `roam audit --json` to a Roam Cloud endpoint — numerical metrics, file paths (or SHA-256 hashes when `--anonymize`), and identifier names only. **No source-code bodies are transmitted**, ever. Inspect the exact payload locally with `--dry-run` before any token is set.
 ```bash
 roam metrics-push --dry-run                            # local-only inspection
@@ -1515,7 +1541,7 @@ Codebase
     |
 [1] Discovery ──── git ls-files (respects .gitignore + .roamignore)
     |
-[2] Parse ──────── tree-sitter AST per file (27 languages)
+[2] Parse ──────── tree-sitter AST per file (28 languages)
     |
 [3] Extract ────── symbols + references (calls, imports, inheritance)
     |
@@ -1614,11 +1640,11 @@ Each factor uses sigmoid health: `h = e^(-signal/scale)` (1 = pristine, approach
 roam-code is the only tool that combines graph algorithms (PageRank, Tarjan SCC, Louvain clustering), git archaeology, architecture simulation, and multi-agent partitioning in a single local CLI with zero API keys.
-Documentation (local HTML in `docs/site/`, CI-deployed via `.github/workflows/pages.yml`):
-- `docs/site/getting-started.html` — tutorial
-- `docs/site/command-reference.html` — examples
-- `docs/site/architecture.html` — diagram + internals
-- `docs/site/landscape.html` — competitor matrix
+Documentation lives at <https://roam-code.com/docs/>:
+- Tutorial — <https://roam-code.com/docs/getting-started>
+- Command reference — <https://roam-code.com/docs/command-reference>
+- Architecture guide — <https://roam-code.com/docs/architecture>
+- Integration tutorials — <https://roam-code.com/docs/integration-tutorials>
 | Capability | roam-code | AI IDEs (Cursor, Windsurf) | AI Agents (Claude Code, Codex) | SAST (SonarQube, CodeQL) |
 |---|---|---|---|---|
@@ -1706,7 +1732,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/              # ~5500 tests, Python 3.9-3.13
+pytest tests/              # ~7,500 tests, Python 3.9-3.13
 # Or use Make targets:
 make dev      # install with dev extras
@@ -1723,8 +1749,8 @@ roam-code/
 ├── action.yml                         # Reusable GitHub Action
 ├── src/roam/
 │   ├── __init__.py                    # Version (from pyproject.toml)
-│   ├── cli.py                         # Click CLI (177 canonical + 7 aliases)
-│   ├── mcp_server.py                  # MCP server (122 tools, 10 resources, 5 prompts)
+│   ├── cli.py                         # Click CLI (198 canonical + 7 aliases)
+│   ├── mcp_server.py                  # MCP server (137 tools, 10 resources, 5 prompts)
 │   ├── db/
 │   │   ├── connection.py              # SQLite (WAL, pragmas, batched IN)
 │   │   ├── schema.py                  # Tables, indexes, migrations
@@ -1795,7 +1821,7 @@ roam-code/
 │       ├── formatter.py               # Token-efficient formatting
 │       ├── sarif.py                   # SARIF 2.1.0 output
 │       └── schema_registry.py         # JSON envelope schema versioning
-└── tests/                             # ~5500 tests across 186 test files
+└── tests/                             # ~7,500 tests across 267 test files
 ```
 </details>
@@ -1818,7 +1844,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 128 MCP tools.
+- [x] Full command and MCP inventory parity in docs: 198 canonical CLI commands (205 with aliases) and 137 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.
@@ -1839,7 +1865,7 @@ Optional: Local semantic ONNX stack (`numpy`, `onnxruntime`, `tokenizers`) via `
 git clone https://github.com/Cranot/roam-code.git
 cd roam-code
 pip install -e .
-pytest tests/   # all ~5500 tests must pass
+pytest tests/   # all ~7,500 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.

roam-code 12.46__tar.gz → 12.50__tar.gz

roam-code 12.46tar.gz → 12.50tar.gz