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

{roam_code-12.47 → roam_code-12.50}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roam-code
-Version: 12.47
+Version: 12.50
 Summary: Instant codebase comprehension for AI coding agents
 Author: Cranot
 License-Expression: Apache-2.0
@@ -66,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 197 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.
 
-*202 commands · 136 MCP tools · 28 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)
@@ -80,6 +80,24 @@ 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.
@@ -162,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).
-- **202 CLI commands, 136 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
 
@@ -336,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 ~197 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 **202 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>
@@ -380,6 +398,7 @@ roam health
 | `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); 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 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 |
@@ -419,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. |
@@ -595,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`
@@ -664,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) |
@@ -988,7 +1009,7 @@ pip install "roam-code[mcp]"
 roam mcp
 ```
 
-136 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)
@@ -1019,7 +1040,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 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 Review + Cloud engines + governance audit-trail toolkit + production-grade rules linting + one-shot v2 stack runner.*
 
@@ -1112,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 |
@@ -1618,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) |
 |---|---|---|---|---|
@@ -1710,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
@@ -1727,8 +1749,8 @@ roam-code/
 ├── action.yml                         # Reusable GitHub Action
 ├── src/roam/
 │   ├── __init__.py                    # Version (from pyproject.toml)
-│   ├── cli.py                         # Click CLI (194 canonical + 7 aliases)
-│   ├── mcp_server.py                  # MCP server (136 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
@@ -1799,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>
@@ -1822,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: 197 canonical CLI commands and 136 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.
@@ -1843,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.47 → roam_code-12.50}/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 197 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.
 
-*202 commands · 136 MCP tools · 28 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)
@@ -18,6 +18,24 @@ 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.
@@ -100,7 +118,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).
-- **202 CLI commands, 136 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
 
@@ -274,7 +292,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 ~197 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 **202 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>
@@ -318,6 +336,7 @@ roam health
 | `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); 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 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 |
@@ -357,7 +376,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. |
@@ -533,7 +552,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`
@@ -602,6 +621,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) |
@@ -926,7 +947,7 @@ pip install "roam-code[mcp]"
 roam mcp
 ```
 
-136 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)
@@ -957,7 +978,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 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 Review + Cloud engines + governance audit-trail toolkit + production-grade rules linting + one-shot v2 stack runner.*
 
@@ -1050,6 +1071,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 |
@@ -1556,11 +1578,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) |
 |---|---|---|---|---|
@@ -1648,7 +1670,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
@@ -1665,8 +1687,8 @@ roam-code/
 ├── action.yml                         # Reusable GitHub Action
 ├── src/roam/
 │   ├── __init__.py                    # Version (from pyproject.toml)
-│   ├── cli.py                         # Click CLI (194 canonical + 7 aliases)
-│   ├── mcp_server.py                  # MCP server (136 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
@@ -1737,7 +1759,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>
@@ -1760,7 +1782,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: 197 canonical CLI commands and 136 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.
@@ -1781,7 +1803,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.47 → roam_code-12.50}/pyproject.toml

@@ -1,10 +1,14 @@
 [build-system]
-requires = ["setuptools>=68.0", "wheel"]
+# setuptools >= 77 is required to emit the PEP 639 ``License-Expression``
+# metadata field. The 12.47 wheel was built with an older setuptools and
+# shipped to PyPI with empty license metadata (the ``Apache-2.0`` SPDX
+# expression below got dropped).
+requires = ["setuptools>=77.0", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "roam-code"
-version = "12.47"
+version = "12.50"
 description = "Instant codebase comprehension for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{roam_code-12.47 → roam_code-12.50}/src/roam/ask/recipes.py

@@ -144,7 +144,7 @@ RECIPES: list[Recipe] = [
         ),
         phase="review",
         perspectives=("blast-radius", "clone-consistency", "intent-alignment"),
-        followups=("roam rules --changed", "roam test-impact"),
+        followups=("roam rules --changed", "roam test-impact", "roam stale-refs (after rename-heavy diffs)"),
         gates=("Stop on high-severity critique findings", "Add or run impacted tests before merge"),
     ),
     Recipe(
@@ -641,6 +641,57 @@ RECIPES: list[Recipe] = [
         followups=("roam visualize --focus <symbol>", "roam fingerprint"),
         gates=("Diagrams complement reading the code, they don't replace it",),
     ),
+    Recipe(
+        name="find-broken-links",
+        intent="Find dangling file references — markdown links / HTML href-src / backtick paths whose target is missing",
+        examples=(
+            "find broken links",
+            "any dead doc links in this repo",
+            "check for stale file references",
+            "what docs point at deleted files",
+            "audit my readme for missing links",
+            "broken doc links after the rename",
+        ),
+        keywords=(
+            # NOTE: keyword bonus is substring-matched against the query
+            # (`"ref" in "refresh"` would over-match), so we keep tokens
+            # that are unlikely to appear inside unrelated words. Tokens
+            # like "ref" / "refs" / "link" are dropped for that reason —
+            # the longer forms below still pick up real intent.
+            "broken",
+            "dangling",
+            "stale",
+            "links",
+            "reference",
+            "references",
+            "dead link",
+            "dead links",
+        ),
+        commands=(("stale-refs", ()),),
+        summary=(
+            "Scans every text file in the repo, surfaces dangling markdown "
+            "links, HTML href/src, and backtick paths whose target no "
+            "longer exists. Includes basename-match rename hints. Pure "
+            "filesystem scan — no index needed."
+        ),
+        phase="audit",
+        perspectives=("doc-hygiene", "post-refactor-cleanup", "ci-gate"),
+        followups=(
+            "roam stale-refs --gate (CI gate, exit 5 on findings)",
+            "roam stale-refs --by-file (group by source doc)",
+            "roam stale-refs --watch (always-on terminal during refactor)",
+            "roam stale-refs --fix preview (auto-rewrite HIGH-confidence)",
+            "roam stale-refs --baseline-save b.json (freeze acknowledged debt)",
+            "roam stale-refs --check-external (validate http(s) URLs too)",
+            "roam lsp (squiggly underlines in your editor as you type)",
+            "roam doc-staleness (stale docstring content)",
+            "roam docs-coverage (missing public-symbol docs)",
+        ),
+        gates=(
+            "Use --gate in CI to block merges with broken doc references",
+            "Suppress historical mentions with --ignore CHANGELOG.md if needed",
+        ),
+    ),
 ]
 
 

{roam_code-12.47 → roam_code-12.50}/src/roam/attest/__init__.py

@@ -19,7 +19,6 @@ v12.1 ships:
 * Embedded CycloneDX 1.7 + OpenVEX predicates
 * Reachability claims integrated with ``roam taint`` output
 * GitHub Artifact Attestations upload action
-* Multi-repo verification over Tailscale (deferred from MVP)
 """
 
 from __future__ import annotations

{roam_code-12.47 → roam_code-12.50}/src/roam/catalog/detectors.py

@@ -1680,7 +1680,7 @@ def list_framework_profiles() -> list[str]:
 
 
 def autodetect_framework_profile() -> str | None:
-    """ sniff package.json / composer.json for known stacks.
+    """sniff package.json / composer.json for known stacks.
 
     Inspects ``package.json`` and ``composer.json`` from the project root
     (current working directory) for the dependency signals that map onto

{roam_code-12.47 → roam_code-12.50}/src/roam/cli.py

@@ -14,7 +14,7 @@ import click
 
 # Lazy-loading command group: imports command modules only when invoked.
 # This avoids importing networkx (~500ms) on every CLI call.
-# Total: 158 invokable command names (155 canonical commands + 3 alias names).
+# Total: 205 invokable command names (198 canonical commands + 7 alias names).
 # If this changes, update README.md, CLAUDE.md, llms-install.md, and docs copy.
 # deprecated commands map to their replacement.  When a user
 # invokes a deprecated name, we still resolve it (no breaking change)
@@ -75,6 +75,8 @@ _COMMANDS = {
     "breaking": ("roam.commands.cmd_breaking", "breaking"),
     "safe-zones": ("roam.commands.cmd_safe_zones", "safe_zones"),
     "doc-staleness": ("roam.commands.cmd_doc_staleness", "doc_staleness"),
+    "stale-refs": ("roam.commands.cmd_stale_refs", "stale_refs"),
+    "lsp": ("roam.commands.cmd_lsp", "lsp"),
     "docs-coverage": ("roam.commands.cmd_docs_coverage", "docs_coverage"),
     "suggest-refactoring": ("roam.commands.cmd_suggest_refactoring", "suggest_refactoring"),
     "plan-refactor": ("roam.commands.cmd_plan_refactor", "plan_refactor"),
@@ -85,6 +87,7 @@ _COMMANDS = {
     "preflight": ("roam.commands.cmd_preflight", "preflight"),
     "permit": ("roam.commands.cmd_permit", "permit_cmd"),
     "postmortem": ("roam.commands.cmd_postmortem", "postmortem_cmd"),
+    "pr-replay": ("roam.commands.cmd_pr_replay", "pr_replay_cmd"),
     "article-12-check": ("roam.commands.cmd_article_12_check", "article_12_check_cmd"),
     "capabilities": ("roam.commands.cmd_capabilities", "capabilities_cmd"),
     "skill-generate": ("roam.commands.cmd_skill_generate", "skill_generate_cmd"),
@@ -282,6 +285,7 @@ _CATEGORIES = {
         "preflight",
         "permit",
         "postmortem",
+        "pr-replay",
         "guard",
         "agent-plan",
         "agent-context",
@@ -437,6 +441,7 @@ _CATEGORIES = {
         "fn-coupling",
         "doc-staleness",
         "docs-coverage",
+        "stale-refs",
         "suggest-refactoring",
         "plan-refactor",
         "conventions",
@@ -936,7 +941,7 @@ def _run_help_all(ctx: click.Context, param: click.Parameter, value: bool) -> No
     "--sarif",
     "sarif_mode",
     is_flag=True,
-    help="Output in SARIF 2.1.0 format (for dead, health, complexity, rules, secrets, algo)",
+    help="Output in SARIF 2.1.0 format (for dead, health, complexity, rules, secrets, algo, stale-refs)",
 )
 @click.option("--budget", type=int, default=0, help="Max output tokens (0=unlimited)")
 @click.option(

{roam_code-12.47 → roam_code-12.50}/src/roam/commands/cmd_audit.py

@@ -86,6 +86,9 @@ def audit(ctx, brief) -> None:
     api = _capture(["api", "--limit", "0"])
     stats = _capture(["stats"])
     hotspots = _capture(["hotspots", "--danger"])
+    # Doc hygiene: dangling markdown links / hrefs / backticks / anchors.
+    # Capped at the default --limit so the audit envelope stays small.
+    stale_refs = _capture(["stale-refs"])
 
     # Top-level scores so consumers can branch fast.
     health_score = _summary_field(health, "health_score", "score")
@@ -97,6 +100,7 @@ def audit(ctx, brief) -> None:
     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")
+    stale_ref_count = _summary_field(stale_refs, "stale_refs", "missing_targets", default=0)
 
     # Verdict — stack-rank the most pressing dimension.
     pressures = []
@@ -106,6 +110,11 @@ def audit(ctx, brief) -> None:
         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}%")
+    # Stale refs cross from "noise" to "pressure" at 10 — one or two
+    # dangling links is a doc-hygiene paper cut, but a wave of them
+    # signals an undocumented rename and breaks AI agents downstream.
+    if isinstance(stale_ref_count, int) and stale_ref_count >= 10:
+        pressures.append(f"{stale_ref_count} stale doc ref(s)")
     if pressures:
         verdict = "AUDIT — pressures: " + ", ".join(pressures)
     else:
@@ -126,6 +135,7 @@ def audit(ctx, brief) -> None:
         "imported_coverage_pct": coverage_pct,
         "file_total": file_total,
         "symbol_total": sym_total,
+        "stale_ref_count": stale_ref_count,
     }
 
     sections = {
@@ -135,6 +145,7 @@ def audit(ctx, brief) -> None:
         "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", {})},
+        "stale_refs": stale_refs if not brief else {"summary": stale_refs.get("summary", {})},
     }
 
     if json_mode:
@@ -164,5 +175,6 @@ def audit(ctx, brief) -> None:
         ("imported coverage %", coverage_pct),
         ("total files", file_total),
         ("total symbols", sym_total),
+        ("stale doc refs", stale_ref_count),
     ]:
         click.echo(f"{label:<28}  {value}")

{roam_code-12.47 → roam_code-12.50}/src/roam/commands/cmd_capabilities.py

@@ -106,7 +106,7 @@ def _populate_registry() -> None:
     """Import known capability-decorated command modules to populate the registry.
 
     Today this lists commands explicitly. Once the decorator has been
-    applied to all 190 commands, this becomes a sweep of
+    applied to every command, this becomes a sweep of
     ``roam.commands.cmd_*``.
     """
     import importlib

{roam_code-12.47 → roam_code-12.50}/src/roam/commands/cmd_config.py

@@ -611,9 +611,7 @@ def _no_mutating_options(
 @click.option("--show", is_flag=True, help="Print current configuration.")
 @click.option("--semantic-status", is_flag=True, help="Show semantic backend readiness and embedding coverage.")
 @click.option("--env", "env_inventory", is_flag=True, help="List every ROAM_* env var read by the codebase.")
-@click.option(
-    "--check", "validate_check", is_flag=True, help="Validate .roam/config.json keys against known schema."
-)
+@click.option("--check", "validate_check", is_flag=True, help="Validate .roam/config.json keys against known schema.")
 @click.option(
     "--weights",
     "show_weights",

{roam_code-12.47 → roam_code-12.50}/src/roam/commands/cmd_doc_staleness.py

@@ -391,7 +391,8 @@ def doc_staleness(ctx, limit, days, include_prose_drift):
 
     Unlike ``docs-coverage`` (which reports missing docs for exported public
     symbols, ranked by PageRank), this command focuses on existing docs that
-    have gone stale.
+    have gone stale. Audits *what* the docs say. For *where* the docs point —
+    dangling links, missing files referenced by README — see ``stale-refs``.
     """
     json_mode = ctx.obj.get("json") if ctx.obj else False
     ensure_index()

{roam_code-12.47 → roam_code-12.50}/src/roam/commands/cmd_docs_coverage.py

@@ -167,7 +167,9 @@ def docs_coverage(ctx, limit, days, threshold, quality):
 
     Unlike ``doc-staleness`` (which scans ALL symbols including private
     ones for stale docstrings), this command focuses on the exported public
-    API surface and prioritizes missing docs by symbol importance.
+    API surface and prioritizes missing docs by symbol importance. For
+    dangling file references (markdown links and backtick paths whose
+    target no longer exists), see ``stale-refs``.
     """
     json_mode = ctx.obj.get("json") if ctx.obj else False
     ensure_index()