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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roam-code
-Version: 12.14
+Version: 12.17
 Summary: Instant codebase comprehension for AI coding agents
 Author: CosmoHac
 License-Expression: MIT
@@ -62,9 +62,9 @@ Dynamic: license-file
 
 **Architectural sight for AI coding agents — before they edit.**
 
-A local code graph (SQLite + tree-sitter + git history) that gives any agent — Claude Code, Cursor, Aider, Continue, your own — five high-leverage verbs: `understand`, `retrieve`, `context`, `preflight`, `critique`. The other 150 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 167 specialised commands are advanced surface for specialised workflows.
 
-*155 commands · 122 MCP tools · 27 languages · 100% local · zero API keys*
+*172 commands · 123 MCP tools · 27 languages · 100% local · zero API keys*
 
 [![PyPI version](https://img.shields.io/pypi/v/roam-code?style=flat-square&color=blue)](https://pypi.org/project/roam-code/)
 [![GitHub stars](https://img.shields.io/github/stars/Cranot/roam-code?style=flat-square)](https://github.com/Cranot/roam-code/stargazers)
@@ -156,7 +156,7 @@ $ roam diff                    # blast radius of uncommitted changes
 - **`personalized_pagerank()`** in `graph/pagerank.py`: NetworkX `personalization=` wrapper with empty-seed fallback to global PR; biases ranking toward query-relevant nodes for the retrieve reranker.
 - **`.roam/config.toml`** (new): zero-dep TOML loader (stdlib `tomllib` → `tomli` → in-tree subset parser). Tunable retrieve weights (`alpha`/`beta`/`gamma`/`delta`/`epsilon`), `tokens_per_line`, `lexical_baseline`, `first_stage_token_cap`, `default_budget`, `default_k`, `default_rerank`.
 - **DX corrections from dogfood pass**: `roam --detail <cmd>` is the canonical group-level flag; misleading "use --detail" hints in 7 commands rewritten to point users at `roam --detail <cmd>`. `--top N` aliased on `complexity`/`algo`/`rules` (`--top 0` means unlimited on `rules`). `roam fingerprint` no longer refuses graphs ≥5,000 symbols (new soft-warn threshold 20k, hard cap 100k).
-- **155 CLI commands, 122 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.
+- **155 CLI commands, 123 MCP tools** (`fleet`, `ask`, `workflow`, `cga`, `eval-retrieve` remain CLI-only; v12 exposes `roam_retrieve`, `roam_critique`, `roam_fleet_plan`, plus 5 v12.1 boolean oracles (`roam_oracle_*`), `roam_taint_classify`, `roam_pytest_fixtures`, and `roam_hover` as MCP tools). 35-tool `core` preset is the default for token-budget-conscious clients.
 
 ## What's New in v11
 
@@ -327,7 +327,7 @@ roam health
 
 ## Commands
 
-**Lead with the 5 verbs.** The [5 core commands](#core-commands) cover ~80% of agent workflows: `understand`, `context`, `retrieve`, `preflight`, `critique`. The remaining 150 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 **155 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 167 commands are detail surface for specialised workflows (taint, fleet, cga, oracle, eval, …) — they're called by agents on demand, not memorised. This is intentional design; under the hood the canonical surface is **172 commands organised into 7 categories** (plus 6 aliases for muscle memory: `algo` → `math`, `weather` → `churn`, `digest` / `snapshot` / `trend` → `trends`, `onboard` → `understand`), but you don't need to know that to start.
 
 <details>
 <summary><strong>Full command reference</strong></summary>
@@ -358,6 +358,23 @@ roam health
 | `roam mcp-setup <platform>` | Generate MCP config snippets for AI platforms: claude-code, cursor, windsurf, vscode, gemini-cli, codex-cli |
 | `roam ci-setup [--platform P] [--write]` | Generate CI/CD pipeline config (GitHub Actions, GitLab CI, Azure Pipelines, Jenkins, Bitbucket) with SARIF + quality gates |
 | `roam adrs [--status S] [--limit N]` | Discover Architecture Decision Records, link to affected code modules, show status and coverage |
+| `roam plugins` | List discovered plugins (commands, detectors, language extractors) registered via `ROAM_PLUGIN_MODULES` or entry points |
+| `roam index-stats` | Report .roam index size, row counts, and SQLite fragmentation; hints when VACUUM or `roam reset` is overdue |
+| `roam test-pyramid` | Count tests by kind (unit/integration/e2e/smoke) using path + filename heuristics; flags inverted pyramids |
+| `roam telemetry` | Surface the opt-in local telemetry ring buffer (slowest + recent calls); enable via `ROAM_TELEMETRY_LOCAL=1` |
+| `roam orphan-imports` | List Python imports that don't resolve to any indexed module or installed package |
+| `roam changelog [--suggest]` | List commits since the last tag, optionally as a Conventional-Commits-bucketed markdown CHANGELOG draft |
+| `roam graph-export [--format graphml\|dot\|jsonl]` | Export the symbol or file dependency graph for external tooling (Gephi, Cytoscape, custom analyses) |
+| `roam help-search <query>` | Fuzzy match across every command's name + help text (replaces grepping `--help-all` output) |
+| `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 why-fail <test>` | Find recently-changed symbols transitively reachable from a failing test |
+| `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 |
 
 ### Daily Workflow
 
@@ -370,7 +387,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 13-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 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 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. |
@@ -970,7 +987,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 122)</strong></summary>
+<summary><strong>MCP tool list (all 123)</strong></summary>
 
 | Tool | Description |
 |------|-------------|
@@ -1093,6 +1110,7 @@ Core preset tools: `roam_affected_tests`, `roam_batch_get`, `roam_batch_search`,
 | `roam_reindex` | Refresh or force-rebuild the index with task-mode support |
 | `roam_reset` | Reset the roam index and cached data |
 | `roam_clean` | Remove stale or orphaned index entries |
+| `roam_catalog` | Machine-readable list of every registered MCP tool with capability flags (read_only / destructive / core) |
 | `roam_batch_search` | Batch symbol search: run multiple pattern queries in a single call |
 | `roam_batch_get` | Batch context retrieval: fetch multiple symbols/files in a single call |
 | `roam_dev_profile` | Developer productivity profile: commit patterns, specialization, and impact |
@@ -1705,7 +1723,7 @@ Optional: Local semantic ONNX stack (`numpy`, `onnxruntime`, `tokenizers`) via `
 ### Shipped
 
 - [x] MCP v2 agent surface: in-process execution, compound operations, presets, schemas, annotations, and compatibility profiles.
-- [x] Full command and MCP inventory parity in docs: 155 canonical CLI commands and 122 MCP tools.
+- [x] Full command and MCP inventory parity in docs: 155 canonical CLI commands and 123 MCP tools.
 - [x] CI hardening: composite action, changed-only mode, trend-aware gates, sticky PR updater, and SARIF guardrails.
 - [x] Performance foundation: FTS5/BM25 search, O(changed) incremental indexing, DB/index optimizations.
 - [x] Agent governance suite: `vibe-check`, `ai-readiness`, `verify`, `ai-ratio`, `duplicates`, advanced `algo` scoring/SARIF.

{roam_code-12.14 → roam_code-12.17}/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 150 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 167 specialised commands are advanced surface for specialised workflows.
 
-*155 commands · 122 MCP tools · 27 languages · 100% local · zero API keys*
+*172 commands · 123 MCP tools · 27 languages · 100% local · zero API keys*
 
 [![PyPI version](https://img.shields.io/pypi/v/roam-code?style=flat-square&color=blue)](https://pypi.org/project/roam-code/)
 [![GitHub stars](https://img.shields.io/github/stars/Cranot/roam-code?style=flat-square)](https://github.com/Cranot/roam-code/stargazers)
@@ -98,7 +98,7 @@ $ roam diff                    # blast radius of uncommitted changes
 - **`personalized_pagerank()`** in `graph/pagerank.py`: NetworkX `personalization=` wrapper with empty-seed fallback to global PR; biases ranking toward query-relevant nodes for the retrieve reranker.
 - **`.roam/config.toml`** (new): zero-dep TOML loader (stdlib `tomllib` → `tomli` → in-tree subset parser). Tunable retrieve weights (`alpha`/`beta`/`gamma`/`delta`/`epsilon`), `tokens_per_line`, `lexical_baseline`, `first_stage_token_cap`, `default_budget`, `default_k`, `default_rerank`.
 - **DX corrections from dogfood pass**: `roam --detail <cmd>` is the canonical group-level flag; misleading "use --detail" hints in 7 commands rewritten to point users at `roam --detail <cmd>`. `--top N` aliased on `complexity`/`algo`/`rules` (`--top 0` means unlimited on `rules`). `roam fingerprint` no longer refuses graphs ≥5,000 symbols (new soft-warn threshold 20k, hard cap 100k).
-- **155 CLI commands, 122 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.
+- **155 CLI commands, 123 MCP tools** (`fleet`, `ask`, `workflow`, `cga`, `eval-retrieve` remain CLI-only; v12 exposes `roam_retrieve`, `roam_critique`, `roam_fleet_plan`, plus 5 v12.1 boolean oracles (`roam_oracle_*`), `roam_taint_classify`, `roam_pytest_fixtures`, and `roam_hover` as MCP tools). 35-tool `core` preset is the default for token-budget-conscious clients.
 
 ## What's New in v11
 
@@ -269,7 +269,7 @@ roam health
 
 ## Commands
 
-**Lead with the 5 verbs.** The [5 core commands](#core-commands) cover ~80% of agent workflows: `understand`, `context`, `retrieve`, `preflight`, `critique`. The remaining 150 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 **155 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 167 commands are detail surface for specialised workflows (taint, fleet, cga, oracle, eval, …) — they're called by agents on demand, not memorised. This is intentional design; under the hood the canonical surface is **172 commands organised into 7 categories** (plus 6 aliases for muscle memory: `algo` → `math`, `weather` → `churn`, `digest` / `snapshot` / `trend` → `trends`, `onboard` → `understand`), but you don't need to know that to start.
 
 <details>
 <summary><strong>Full command reference</strong></summary>
@@ -300,6 +300,23 @@ roam health
 | `roam mcp-setup <platform>` | Generate MCP config snippets for AI platforms: claude-code, cursor, windsurf, vscode, gemini-cli, codex-cli |
 | `roam ci-setup [--platform P] [--write]` | Generate CI/CD pipeline config (GitHub Actions, GitLab CI, Azure Pipelines, Jenkins, Bitbucket) with SARIF + quality gates |
 | `roam adrs [--status S] [--limit N]` | Discover Architecture Decision Records, link to affected code modules, show status and coverage |
+| `roam plugins` | List discovered plugins (commands, detectors, language extractors) registered via `ROAM_PLUGIN_MODULES` or entry points |
+| `roam index-stats` | Report .roam index size, row counts, and SQLite fragmentation; hints when VACUUM or `roam reset` is overdue |
+| `roam test-pyramid` | Count tests by kind (unit/integration/e2e/smoke) using path + filename heuristics; flags inverted pyramids |
+| `roam telemetry` | Surface the opt-in local telemetry ring buffer (slowest + recent calls); enable via `ROAM_TELEMETRY_LOCAL=1` |
+| `roam orphan-imports` | List Python imports that don't resolve to any indexed module or installed package |
+| `roam changelog [--suggest]` | List commits since the last tag, optionally as a Conventional-Commits-bucketed markdown CHANGELOG draft |
+| `roam graph-export [--format graphml\|dot\|jsonl]` | Export the symbol or file dependency graph for external tooling (Gephi, Cytoscape, custom analyses) |
+| `roam help-search <query>` | Fuzzy match across every command's name + help text (replaces grepping `--help-all` output) |
+| `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 why-fail <test>` | Find recently-changed symbols transitively reachable from a failing test |
+| `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 |
 
 ### Daily Workflow
 
@@ -312,7 +329,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 13-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 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 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. |
@@ -912,7 +929,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 122)</strong></summary>
+<summary><strong>MCP tool list (all 123)</strong></summary>
 
 | Tool | Description |
 |------|-------------|
@@ -1035,6 +1052,7 @@ Core preset tools: `roam_affected_tests`, `roam_batch_get`, `roam_batch_search`,
 | `roam_reindex` | Refresh or force-rebuild the index with task-mode support |
 | `roam_reset` | Reset the roam index and cached data |
 | `roam_clean` | Remove stale or orphaned index entries |
+| `roam_catalog` | Machine-readable list of every registered MCP tool with capability flags (read_only / destructive / core) |
 | `roam_batch_search` | Batch symbol search: run multiple pattern queries in a single call |
 | `roam_batch_get` | Batch context retrieval: fetch multiple symbols/files in a single call |
 | `roam_dev_profile` | Developer productivity profile: commit patterns, specialization, and impact |
@@ -1647,7 +1665,7 @@ Optional: Local semantic ONNX stack (`numpy`, `onnxruntime`, `tokenizers`) via `
 ### Shipped
 
 - [x] MCP v2 agent surface: in-process execution, compound operations, presets, schemas, annotations, and compatibility profiles.
-- [x] Full command and MCP inventory parity in docs: 155 canonical CLI commands and 122 MCP tools.
+- [x] Full command and MCP inventory parity in docs: 155 canonical CLI commands and 123 MCP tools.
 - [x] CI hardening: composite action, changed-only mode, trend-aware gates, sticky PR updater, and SARIF guardrails.
 - [x] Performance foundation: FTS5/BM25 search, O(changed) incremental indexing, DB/index optimizations.
 - [x] Agent governance suite: `vibe-check`, `ai-readiness`, `verify`, `ai-ratio`, `duplicates`, advanced `algo` scoring/SARIF.

{roam_code-12.14 → roam_code-12.17}/pyproject.toml

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

roam_code-12.17/src/roam/__main__.py

@@ -0,0 +1,14 @@
+"""Allow running as python -m roam."""
+
+import sys
+
+from roam.cli import cli
+
+# Pass 40 — graceful Ctrl-C: exit 130 (SIGINT convention) without
+# spilling a Python traceback. Long-running commands still leave any
+# committed DB rows in place — this just suppresses the noise.
+try:
+    cli()
+except KeyboardInterrupt:
+    sys.stderr.write("\nInterrupted (Ctrl-C). Partial work has been preserved; rerun the command to continue.\n")
+    sys.exit(130)

{roam_code-12.14 → roam_code-12.17}/src/roam/ask/recipes.py

@@ -376,6 +376,271 @@ RECIPES: list[Recipe] = [
         followups=("roam fingerprint", "roam health --json"),
         gates=("Stop on new cycles", "Extract boundaries before moving highly coupled modules"),
     ),
+    # 12.15 — recipe expansion. Cover the agent workflows that
+    # showed up repeatedly in dogfood but weren't classified.
+    Recipe(
+        name="trace-bug",
+        intent="Diagnose a failing test, error, or bug back to its root cause",
+        examples=(
+            "why is my test failing",
+            "trace this exception to its source",
+            "debug this error",
+            "what's causing this bug",
+        ),
+        keywords=("debug", "bug", "error", "failing", "broken", "crash", "exception", "traceback"),
+        commands=(
+            ("diagnose", ("{symbol}",)),
+            ("trace", ("{symbol}",)),
+            ("affected-tests", ("{symbol}",)),
+        ),
+        summary=(
+            "Risk-ranked upstream/downstream suspects, dependency paths, and the "
+            "tests that exercise the symbol — three lenses on the same bug."
+        ),
+        phase="diagnose",
+        perspectives=("root-cause", "execution-path", "test-coverage"),
+        followups=("roam context {symbol}", "roam diff"),
+        gates=("Confirm reproduction before changing anything",),
+    ),
+    Recipe(
+        name="who-owns",
+        intent="Identify the human owners or expert authors of a symbol or area",
+        examples=(
+            "who owns this code",
+            "who should review my change to UserSession",
+            "who is the expert on auth",
+            "find the maintainer",
+        ),
+        keywords=("owner", "owns", "expert", "maintainer", "author", "review", "loop in"),
+        commands=(
+            ("owner", ("{symbol}",)),
+            ("suggest-reviewers", ()),
+            ("bus-factor", ()),
+        ),
+        summary=(
+            "Code-ownership map (CODEOWNERS + git churn) plus suggested reviewers "
+            "and bus-factor warnings. Use to route changes through the right humans."
+        ),
+        phase="ownership",
+        perspectives=("ownership", "review-routing", "bus-factor"),
+        followups=("roam codeowners --check", "roam dev-profile <author>"),
+        gates=("Loop in original author when bus-factor is 1",),
+    ),
+    Recipe(
+        name="what-changed",
+        intent="Summarise recent activity in a file, symbol, or directory",
+        examples=(
+            "what changed in this file recently",
+            "show recent commits to auth.py",
+            "what's the history of UserSession",
+            "who last touched this",
+        ),
+        keywords=("recent", "history", "commits", "lately", "last week", "last month", "what changed"),
+        commands=(
+            ("weather", ()),
+            ("trends", ("--days", "30")),
+        ),
+        summary=("Hot file weather plus 30-day trend snapshot. Use to spot churn spikes before reviewing a PR."),
+        phase="discover",
+        perspectives=("churn", "velocity", "regression-risk"),
+        followups=("roam diagnose <symbol>", "roam pr-risk"),
+        gates=("Re-run trends weekly to track movement",),
+    ),
+    Recipe(
+        name="audit-security",
+        intent="Run a security audit: secrets, taint flows, dependency vulnerabilities",
+        examples=(
+            "audit security",
+            "any vulnerabilities here",
+            "find secrets and SQLi",
+            "check for security issues",
+        ),
+        keywords=("security", "audit", "vulnerability", "vuln", "secret", "taint", "sqli", "xss"),
+        commands=(
+            ("secrets", ()),
+            ("taint", ()),
+            ("vulns", ()),
+            ("supply-chain", ()),
+        ),
+        summary=(
+            "Four parallel security passes: secret leakage, taint reachability, "
+            "known-CVE mapping, supply-chain trust. Treat any HIGH severity "
+            "as a release blocker."
+        ),
+        phase="security",
+        perspectives=("secrets", "data-flow", "supply-chain", "vulnerability-reachability"),
+        followups=("roam taint --rules-pack sqli", "roam cga emit --include-taint"),
+        gates=("Stop on any HIGH severity finding",),
+    ),
+    Recipe(
+        name="explore-impact",
+        intent="Predict the blast radius and risk of an upcoming change",
+        examples=(
+            "what will break if I change UserSession",
+            "predict the impact of editing auth.py",
+            "blast radius of this change",
+            "is this change risky",
+        ),
+        keywords=("impact", "blast", "break", "predict", "ripple", "risky"),
+        commands=(
+            ("impact", ("{symbol}",)),
+            ("affected-tests", ("{symbol}",)),
+            ("preflight", ("{symbol}",)),
+        ),
+        summary=(
+            "Transitive blast radius (PageRank-personalized), test coverage, "
+            "and the unified preflight verdict — three lenses on one change."
+        ),
+        phase="scope",
+        perspectives=("blast-radius", "test-coverage", "risk"),
+        followups=("roam closure {symbol}", "roam diff"),
+        gates=("Stop on CRITICAL preflight risk", "Cover all impacted tests before merging"),
+    ),
+    Recipe(
+        name="find-similar",
+        intent="Find code that duplicates or closely resembles a target",
+        examples=(
+            "find duplicates of this function",
+            "are there similar implementations of UserSession",
+            "show me clones",
+            "what code looks like this",
+        ),
+        keywords=("duplicate", "clone", "similar", "copy", "redundant", "dedup"),
+        commands=(
+            ("clones", ("--threshold", "0.7")),
+            ("duplicates", ()),
+        ),
+        summary=(
+            "AST-hash clone detection + lexical duplicate finder. Use to consolidate copy-paste before a refactor."
+        ),
+        phase="cleanup",
+        perspectives=("clone-detection", "deduplication", "consolidation"),
+        followups=("roam suggest-refactoring", "roam plan-refactor"),
+        gates=("Confirm tests still pass after consolidation",),
+    ),
+    Recipe(
+        name="why-this-exists",
+        intent="Understand why a piece of code exists — purpose, history, role",
+        examples=(
+            "why does this function exist",
+            "what is UserSession for",
+            "explain this code",
+            "purpose of handle_login",
+        ),
+        keywords=("why", "purpose", "what for", "explain", "describe", "role"),
+        commands=(
+            ("why", ("{symbol}",)),
+            ("symbol", ("{symbol}",)),
+            ("hover", ("{symbol}",)),
+        ),
+        summary=(
+            "Architectural role classification, full symbol metadata, and a "
+            "compact one-line summary — three views on one symbol's purpose."
+        ),
+        phase="understand",
+        perspectives=("role", "metadata", "summary"),
+        followups=("roam context {symbol}", "roam trace <caller> {symbol}"),
+        gates=("Don't repeat already-known intent — focus on unstated rationale",),
+    ),
+    Recipe(
+        name="check-pr",
+        intent="Run a full pre-merge review on a pull request",
+        examples=(
+            "review this PR",
+            "is my pull request ready to merge",
+            "audit the diff",
+            "pre-merge check",
+        ),
+        keywords=("pr", "pull request", "merge", "ship", "review", "ready"),
+        commands=(
+            ("pr-risk", ()),
+            ("pr-diff", ()),
+            ("breaking", ()),
+        ),
+        summary=(
+            "Risk score (with driver named), structural diff impact, and "
+            "breaking-change detection. Pair with `roam critique` for the "
+            "graph-grounded patch verifier."
+        ),
+        phase="review",
+        perspectives=("risk-score", "structural-diff", "breaking-changes"),
+        followups=("roam critique", "roam suggest-reviewers"),
+        gates=("Stop on HIGH risk score", "Stop on any breaking change without major version bump"),
+    ),
+    Recipe(
+        name="explore-tests",
+        intent="Map test coverage, gaps, and orphaned tests",
+        examples=(
+            "show test coverage",
+            "find untested code",
+            "what tests exercise this",
+            "are there orphan tests",
+        ),
+        keywords=("test", "coverage", "untested", "tests", "fixtures"),
+        commands=(
+            ("test-map", ()),
+            ("coverage-gaps", ("--gate-pattern", ".*")),
+            ("affected-tests", ("{symbol}",)),
+        ),
+        summary=(
+            "Source↔test mapping, coverage gaps for the gate pattern, "
+            "and the test set that exercises a specific symbol."
+        ),
+        phase="testing",
+        perspectives=("coverage", "test-discovery", "untested-paths"),
+        followups=("roam test-scaffold {symbol}", "roam pytest-fixtures"),
+        gates=("Cover every gate-protected entry point",),
+    ),
+    Recipe(
+        name="dependency-update",
+        intent="Assess the safety of upgrading or removing a dependency",
+        examples=(
+            "is it safe to upgrade flask",
+            "what depends on requests",
+            "remove this package",
+            "audit this dependency",
+        ),
+        keywords=("upgrade", "depend", "package", "library", "version", "lock", "remove"),
+        commands=(
+            ("supply-chain", ()),
+            ("vulns", ()),
+            ("vuln-reach", ()),
+        ),
+        summary=(
+            "Dependency tree + known-CVE mapping + reachability. The "
+            "reachability layer turns a 'CVE in transitive dep' alert into "
+            "an actionable 'this CVE is reachable from your code'."
+        ),
+        phase="dependency",
+        perspectives=("supply-chain", "vulnerability", "reachability"),
+        followups=("roam sbom --format cyclonedx", "roam cga emit"),
+        gates=("Block upgrades that introduce reachable HIGH CVEs",),
+    ),
+    Recipe(
+        name="visualize-architecture",
+        intent="Generate a diagram of the architecture, layers, or a focus area",
+        examples=(
+            "show me an architecture diagram",
+            "draw the layers",
+            "visualize the auth subsystem",
+            "diagram of UserSession's neighborhood",
+        ),
+        keywords=("diagram", "visualize", "draw", "graph", "mermaid", "picture", "layout"),
+        commands=(
+            ("visualize", ()),
+            ("layers", ()),
+            ("clusters", ()),
+        ),
+        summary=(
+            "Mermaid architecture diagram + topological layer breakdown + "
+            "Louvain cluster grouping. Use the diagram in PR descriptions "
+            "or design documents."
+        ),
+        phase="architecture",
+        perspectives=("structure", "layers", "clusters"),
+        followups=("roam visualize --focus <symbol>", "roam fingerprint"),
+        gates=("Diagrams complement reading the code, they don't replace it",),
+    ),
 ]