roam-code 12.41__tar.gz → 12.43__tar.gz

{roam_code-12.41 → roam_code-12.43}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roam-code
-Version: 12.41
+Version: 12.43
 Summary: Instant codebase comprehension for AI coding agents
 Author: CosmoHac
 License-Expression: Apache-2.0
@@ -64,9 +64,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 185 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 188 specialised commands are advanced surface for specialised workflows.
 
-*190 commands · 136 MCP tools · 27 languages · 100% local · zero API keys*
+*193 commands · 136 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)
@@ -334,7 +334,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 185 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 **190 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 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.
 
 <details>
 <summary><strong>Full command reference</strong></summary>
@@ -383,6 +383,9 @@ roam health
 | `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 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 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_code-12.41 → roam_code-12.43}/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 185 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 188 specialised commands are advanced surface for specialised workflows.
 
-*190 commands · 136 MCP tools · 27 languages · 100% local · zero API keys*
+*193 commands · 136 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)
@@ -274,7 +274,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 185 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 **190 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 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.
 
 <details>
 <summary><strong>Full command reference</strong></summary>
@@ -323,6 +323,9 @@ roam health
 | `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 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 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_code-12.41 → roam_code-12.43}/pyproject.toml

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

roam_code-12.43/src/roam/capability.py

@@ -0,0 +1,250 @@
+"""Capability Registry — decorator-driven introspection for roam commands.
+
+Phase 1 of the v2 monetization plan (per build_priorities.md). The
+architect's correction: the per-command capability YAML must be derived
+from decorators, not hand-edited. This module implements the decorator
+plus an emitter that walks all registered commands and produces a
+machine-readable manifest.
+
+Usage:
+
+    from roam.capability import roam_capability
+
+    @roam_capability(
+        category="review",
+        summary="Verify a patch against the indexed graph.",
+        inputs=["diff_text"],
+        outputs=["verdict", "findings"],
+        ai_safe=True,
+        since="12.0",
+    )
+    @click.command()
+    def critique(...):
+        ...
+
+The introspection layer (``CapabilityRegistry``) collects every
+``@roam_capability``-decorated callable when it's imported, and
+``emit_yaml`` / ``emit_json`` serialises the catalog.
+
+The downstream consumer is the Roam Review GitHub App (Phase 2): it
+reads the manifest at startup so it knows which commands are AI-safe to
+expose as webhook actions vs which need human approval.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+@dataclass(frozen=True)
+class Capability:
+    """One decorated command's metadata."""
+
+    name: str
+    category: str
+    summary: str
+    inputs: tuple[str, ...] = ()
+    outputs: tuple[str, ...] = ()
+    examples: tuple[str, ...] = ()
+    tags: tuple[str, ...] = ()
+    ai_safe: bool = False
+    requires_index: bool = True
+    since: str | None = None
+    deprecated: bool = False
+    module: str = ""
+    func_name: str = ""
+
+
+@dataclass
+class CapabilityRegistry:
+    """Process-wide registry of capability-decorated callables.
+
+    Populated as a side-effect of importing any decorated command module.
+    """
+
+    items: dict[str, Capability] = field(default_factory=dict)
+
+    def register(self, cap: Capability) -> None:
+        if cap.name in self.items:
+            existing = self.items[cap.name]
+            if existing.module != cap.module:
+                raise ValueError(
+                    f"capability name collision: {cap.name!r} already registered from "
+                    f"{existing.module!r}; tried to register from {cap.module!r}"
+                )
+        self.items[cap.name] = cap
+
+    def get(self, name: str) -> Capability | None:
+        return self.items.get(name)
+
+    def all(self) -> list[Capability]:
+        return sorted(self.items.values(), key=lambda c: (c.category, c.name))
+
+    def by_category(self) -> dict[str, list[Capability]]:
+        out: dict[str, list[Capability]] = {}
+        for cap in self.all():
+            out.setdefault(cap.category, []).append(cap)
+        return out
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": 1,
+            "generated_by": "roam.capability.CapabilityRegistry",
+            "count": len(self.items),
+            "capabilities": [
+                {
+                    "name": cap.name,
+                    "category": cap.category,
+                    "summary": cap.summary,
+                    "inputs": list(cap.inputs),
+                    "outputs": list(cap.outputs),
+                    "examples": list(cap.examples),
+                    "tags": list(cap.tags),
+                    "ai_safe": cap.ai_safe,
+                    "requires_index": cap.requires_index,
+                    "since": cap.since,
+                    "deprecated": cap.deprecated,
+                    "module": cap.module,
+                    "func_name": cap.func_name,
+                }
+                for cap in self.all()
+            ],
+        }
+
+
+REGISTRY = CapabilityRegistry()
+
+
+def roam_capability(
+    *,
+    category: str,
+    summary: str,
+    name: str | None = None,
+    inputs: tuple[str, ...] | list[str] = (),
+    outputs: tuple[str, ...] | list[str] = (),
+    examples: tuple[str, ...] | list[str] = (),
+    tags: tuple[str, ...] | list[str] = (),
+    ai_safe: bool = False,
+    requires_index: bool = True,
+    since: str | None = None,
+    deprecated: bool = False,
+) -> Callable[[F], F]:
+    """Mark a Click command as a capability for introspection.
+
+    Place ABOVE ``@click.command()`` so the decorator wraps a Click
+    Command instance — the introspection then has access to the
+    Click metadata as well.
+    """
+
+    def deco(func: F) -> F:
+        cap_name = name or _derive_name(func)
+        # For Click Commands, the original module is on the callback
+        callback = getattr(func, "callback", None)
+        module = (
+            getattr(callback, "__module__", "")
+            if callback is not None
+            else getattr(func, "__module__", "")
+        )
+        func_name = (
+            getattr(callback, "__name__", "")
+            if callback is not None
+            else getattr(func, "__name__", "")
+        )
+        cap = Capability(
+            name=cap_name,
+            category=category,
+            summary=summary,
+            inputs=tuple(inputs),
+            outputs=tuple(outputs),
+            examples=tuple(examples),
+            tags=tuple(tags),
+            ai_safe=ai_safe,
+            requires_index=requires_index,
+            since=since,
+            deprecated=deprecated,
+            module=module,
+            func_name=func_name,
+        )
+        REGISTRY.register(cap)
+        # Stash on the function for later introspection (e.g. roam capabilities --explain X)
+        setattr(func, "__roam_capability__", cap)
+        return func
+
+    return deco
+
+
+def _derive_name(func: Callable[..., Any]) -> str:
+    """Derive the CLI command name from the function or Click Command.
+
+    Order of preference:
+      1. ``func.name`` — set by ``@click.command(name=...)``
+      2. ``func.__name__`` — set by Python on a function
+      3. ``func.callback.__name__`` — Click stores the original here
+    Strips a leading ``cmd_`` and converts underscores to dashes.
+    """
+    candidates: list[str] = []
+    name_attr = getattr(func, "name", None)
+    if isinstance(name_attr, str) and name_attr:
+        candidates.append(name_attr)
+    fn_name = getattr(func, "__name__", "")
+    if isinstance(fn_name, str) and fn_name:
+        candidates.append(fn_name)
+    callback = getattr(func, "callback", None)
+    if callback is not None:
+        cb_name = getattr(callback, "__name__", "")
+        if isinstance(cb_name, str) and cb_name:
+            candidates.append(cb_name)
+    for cand in candidates:
+        if cand and cand != "Command":  # skip the click class name
+            if cand.startswith("cmd_"):
+                cand = cand[4:]
+            return cand.replace("_", "-")
+    return "<anonymous>"
+
+
+def emit_yaml() -> str:
+    """Emit the capability catalog as YAML using the in-tree minimal emitter.
+
+    Avoids the PyYAML dependency to stay aligned with the rules engine's
+    fallback strategy (see roam.rules.engine._emit_simple_yaml).
+    """
+    data = REGISTRY.to_dict()
+    lines: list[str] = [
+        f"schema_version: {data['schema_version']}",
+        f"generated_by: {data['generated_by']}",
+        f"count: {data['count']}",
+        "capabilities:",
+    ]
+    for cap in data["capabilities"]:
+        lines.append(f"  - name: {cap['name']}")
+        lines.append(f"    category: {cap['category']}")
+        lines.append(f"    summary: {_yaml_str(cap['summary'])}")
+        if cap["inputs"]:
+            lines.append(f"    inputs: [{', '.join(_yaml_str(s) for s in cap['inputs'])}]")
+        if cap["outputs"]:
+            lines.append(f"    outputs: [{', '.join(_yaml_str(s) for s in cap['outputs'])}]")
+        if cap["examples"]:
+            lines.append("    examples:")
+            for ex in cap["examples"]:
+                lines.append(f"      - {_yaml_str(ex)}")
+        if cap["tags"]:
+            lines.append(f"    tags: [{', '.join(_yaml_str(t) for t in cap['tags'])}]")
+        lines.append(f"    ai_safe: {str(cap['ai_safe']).lower()}")
+        lines.append(f"    requires_index: {str(cap['requires_index']).lower()}")
+        if cap["since"]:
+            lines.append(f"    since: {_yaml_str(cap['since'])}")
+        if cap["deprecated"]:
+            lines.append("    deprecated: true")
+        lines.append(f"    module: {cap['module']}")
+        lines.append(f"    func_name: {cap['func_name']}")
+    return "\n".join(lines) + "\n"
+
+
+def _yaml_str(s: str) -> str:
+    """Quote a string for YAML if needed."""
+    if any(c in s for c in (':', '#', '\n', '"', "'", '[', ']', '{', '}', ',', '&', '*', '!', '|', '>')):
+        return '"' + s.replace('\\', '\\\\').replace('"', '\\"') + '"'
+    return s

{roam_code-12.41 → roam_code-12.43}/src/roam/catalog/detectors.py

@@ -2485,6 +2485,135 @@ def detect_async_blocking_sleep(conn: sqlite3.Connection) -> list[dict]:
     return results
 
 
+# R5 (2026-05-07) — `asyncio.create_task(coro())` whose return value is
+# discarded. The task is gc-collected before it runs to completion. The
+# fix is to either store the task in a long-lived collection or `await`
+# it. PEP 649 / Python 3.11+ docs explicitly call this a footgun.
+_RE_FIRE_AND_FORGET_TASK = re.compile(
+    r"^\s*(?:asyncio\.)?create_task\s*\(",
+    re.MULTILINE,
+)
+_RE_STORED_TASK = re.compile(
+    r"^\s*(?:\w+\s*[+\-*/]?=\s*|\w+\s*\.\s*append\s*\(\s*|\w+\s*\.\s*add\s*\(\s*|return\s+|await\s+)"
+    r"(?:asyncio\.)?create_task\s*\(",
+    re.MULTILINE,
+)
+
+
+def detect_async_fire_and_forget(conn: sqlite3.Connection) -> list[dict]:
+    """``asyncio.create_task(...)`` whose return value is discarded.
+
+    Background tasks that aren't held in a long-lived reference get
+    garbage-collected before they finish. Python 3.11+ explicitly warns
+    about this footgun. The fix is to store the task somewhere that
+    survives until ``await`` time, or just ``await`` it directly.
+
+    Conservative: Python only, only fires when the line clearly creates
+    a task without storing it.
+    """
+    try:
+        rows = conn.execute(
+            "SELECT s.id, s.name, s.qualified_name, s.kind, f.path AS file_path, "
+            "s.line_start, s.line_end "
+            "FROM symbols s "
+            "JOIN files f ON s.file_id = f.id "
+            "WHERE s.kind IN ('function', 'method') "
+            "AND f.language = 'python'"
+        ).fetchall()
+    except Exception:
+        return []
+    results = []
+    for r in rows:
+        if _is_test_path(r["file_path"]):
+            continue
+        snippet = _read_symbol_source(r["file_path"], r["line_start"], r["line_end"]) or ""
+        if "create_task" not in snippet:
+            continue
+        # Subtract stored-task lines from total create_task occurrences
+        total = len(_RE_FIRE_AND_FORGET_TASK.findall(snippet))
+        stored = len(_RE_STORED_TASK.findall(snippet))
+        leaked = total - stored
+        if leaked <= 0:
+            continue
+        results.append(
+            _finding(
+                "async-fire-and-forget-task",
+                "leaked-asyncio-task",
+                r,
+                f"{leaked} asyncio.create_task call(s) whose return value isn't stored — gc may discard the task before it completes",
+                "high",
+                snippet=snippet,
+                matched_patterns=[
+                    f"create_task occurrences: {total}",
+                    f"stored: {stored}, leaked: {leaked}",
+                ],
+            )
+        )
+        results[-1]["fix"] = "Store the task: `tasks.append(asyncio.create_task(coro()))` and await it later, or `await asyncio.create_task(coro())` directly."
+    return results
+
+
+# R5 (2026-05-07) — `asyncio.run(...)` inside an async function. This
+# raises RuntimeError because the event loop is already running. The
+# fix is to call the coroutine directly with `await` instead.
+_RE_NESTED_ASYNCIO_RUN = re.compile(
+    r"^\s*(?:asyncio\.)?run\s*\(",
+    re.MULTILINE,
+)
+
+
+def detect_async_nested_run(conn: sqlite3.Connection) -> list[dict]:
+    """``asyncio.run()`` invoked inside another async function.
+
+    ``asyncio.run`` creates a new event loop. If one is already running
+    (which it is, inside an async function), this raises ``RuntimeError:
+    asyncio.run() cannot be called from a running event loop``. The fix
+    is to ``await`` the coroutine directly.
+
+    Python only, fires only when the host is async.
+    """
+    try:
+        rows = conn.execute(
+            "SELECT s.id, s.name, s.qualified_name, s.kind, f.path AS file_path, "
+            "s.line_start, s.line_end "
+            "FROM symbols s "
+            "JOIN files f ON s.file_id = f.id "
+            "WHERE s.kind IN ('function', 'method') "
+            "AND s.is_async = 1 "
+            "AND f.language = 'python'"
+        ).fetchall()
+    except Exception:
+        return []
+    results = []
+    for r in rows:
+        if _is_test_path(r["file_path"]):
+            continue
+        snippet = _read_symbol_source(r["file_path"], r["line_start"], r["line_end"]) or ""
+        if "asyncio.run(" not in snippet:
+            continue
+        # Heuristic: must be `asyncio.run(` (not `await asyncio.run(`); the
+        # latter is also wrong but caught by other linters more reliably.
+        match_count = snippet.count("asyncio.run(")
+        if match_count == 0:
+            continue
+        results.append(
+            _finding(
+                "async-nested-run",
+                "asyncio-run-in-async",
+                r,
+                "asyncio.run() invoked inside an async function — raises RuntimeError at runtime (loop already running)",
+                "high",
+                snippet=snippet,
+                matched_patterns=[
+                    "is_async = 1",
+                    f"asyncio.run( occurrences: {match_count}",
+                ],
+            )
+        )
+        results[-1]["fix"] = "Replace `asyncio.run(coro())` with `await coro()` — you're already inside an event loop."
+    return results
+
+
 # X2 (2026-05-06) — Python: `except Exception:` / `except BaseException:`
 # without `raise` is the canonical "swallowing bug" pattern. Catches
 # KeyboardInterrupt, MemoryError, SystemExit silently. The fix is to
@@ -3927,6 +4056,8 @@ _MATH_DETECTORS = [
     ("io-in-loop", "loop-query", detect_io_in_loop),
     ("serial-await-loop", "for-of-await", detect_serial_await_loop),
     ("async-blocking-sleep", "blocking-call-in-async", detect_async_blocking_sleep),
+    ("async-fire-and-forget-task", "leaked-asyncio-task", detect_async_fire_and_forget),
+    ("async-nested-run", "asyncio-run-in-async", detect_async_nested_run),
     ("broad-except-swallow", "swallow-exception", detect_broad_except_swallow),
     ("spread-accumulator", "spread-rebind", detect_spread_accumulator),
     ("defer-in-loop", "loop-defer", detect_defer_in_loop),

{roam_code-12.41 → roam_code-12.43}/src/roam/cli.py

@@ -86,6 +86,9 @@ _COMMANDS = {
     "permit": ("roam.commands.cmd_permit", "permit_cmd"),
     "postmortem": ("roam.commands.cmd_postmortem", "postmortem_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"),
+    "compare": ("roam.commands.cmd_compare", "compare_cmd"),
     "guard": ("roam.commands.cmd_guard", "guard"),
     "init": ("roam.commands.cmd_init", "init"),
     "config": ("roam.commands.cmd_config", "config"),
@@ -290,6 +293,9 @@ _CATEGORIES = {
         "audit-trail-export",
         "audit-trail-conformance-check",
         "article-12-check",
+        "capabilities",
+        "skill-generate",
+        "compare",
         "dogfood",
         "suppress",
         "pr-diff",

{roam_code-12.41 → roam_code-12.43}/src/roam/commands/cmd_article_12_check.py

@@ -295,6 +295,23 @@ def _render_pdf_report(markdown_text: str, output_path: Path) -> bool:
     return True
 
 
+from roam.capability import roam_capability
+
+
+@roam_capability(
+    category="compliance",
+    summary="EU AI Act Article 12 readiness assessment — 6-item checklist over the current repo.",
+    inputs=["repo_path"],
+    outputs=["readiness_score", "checklist_results", "markdown_report"],
+    examples=[
+        "roam article-12-check",
+        "roam article-12-check --pdf report.pdf",
+    ],
+    tags=["compliance", "eu-ai-act", "audit", "phase0"],
+    ai_safe=True,
+    requires_index=False,
+    since="12.40",
+)
 @click.command(name="article-12-check")
 @click.option(
     "--output",

roam_code-12.43/src/roam/commands/cmd_capabilities.py

@@ -0,0 +1,129 @@
+"""roam capabilities — emit the capability registry as YAML / JSON.
+
+Phase 1 of the v2 monetization plan. Reads the in-process
+``roam.capability.REGISTRY`` (populated by ``@roam_capability``
+decorators on commands as they're imported) and writes a manifest
+suitable for downstream consumers (Roam Review GitHub App, MCP server,
+documentation generators).
+"""
+
+from __future__ import annotations
+
+import json
+
+import click
+
+from roam.capability import REGISTRY, emit_yaml
+from roam.output.formatter import json_envelope, to_json
+
+
+@click.command()
+@click.option(
+    "--emit",
+    type=click.Choice(["yaml", "json", "text"]),
+    default="text",
+    show_default=True,
+    help="Output format. yaml/json for machine consumption, text for human reading.",
+)
+@click.option(
+    "--category",
+    type=str,
+    default=None,
+    help="Filter to one category (e.g. review, refactor, architecture).",
+)
+@click.option(
+    "--ai-safe-only",
+    is_flag=True,
+    help="Show only capabilities marked ai_safe=True (safe for an AI agent to call without human approval).",
+)
+@click.pass_context
+def capabilities_cmd(ctx, emit: str, category: str | None, ai_safe_only: bool) -> None:
+    """Emit the capability registry — every command's machine-readable shape.
+
+    The manifest is what the Roam Review GitHub App reads to decide which
+    commands an AI agent can call without human approval, and what tools
+    the MCP server should expose by default.
+
+    Imports trigger registration. Run ``roam capabilities --emit yaml``
+    to produce a stable manifest after every release.
+    """
+    # Force-load known command modules so the registry is populated.
+    _populate_registry()
+
+    items = REGISTRY.all()
+    if category:
+        items = [c for c in items if c.category == category]
+    if ai_safe_only:
+        items = [c for c in items if c.ai_safe]
+
+    json_mode = ctx.obj.get("json") if ctx.obj else False
+
+    if emit == "yaml":
+        click.echo(emit_yaml())
+        return
+    if emit == "json" or json_mode:
+        envelope = json_envelope(
+            "capabilities",
+            summary={
+                "count": len(items),
+                "category_filter": category,
+                "ai_safe_only": ai_safe_only,
+            },
+            capabilities=[
+                {
+                    "name": c.name,
+                    "category": c.category,
+                    "summary": c.summary,
+                    "inputs": list(c.inputs),
+                    "outputs": list(c.outputs),
+                    "ai_safe": c.ai_safe,
+                    "since": c.since,
+                }
+                for c in items
+            ],
+        )
+        click.echo(to_json(envelope))
+        return
+
+    # Text output
+    if not items:
+        click.echo("No registered capabilities (registry empty).")
+        return
+    click.echo(f"{len(items)} registered capabilities:")
+    last_cat = None
+    for c in items:
+        if c.category != last_cat:
+            click.echo(f"\n  [{c.category}]")
+            last_cat = c.category
+        flags = []
+        if c.ai_safe:
+            flags.append("ai-safe")
+        if c.deprecated:
+            flags.append("deprecated")
+        flag_str = f" ({', '.join(flags)})" if flags else ""
+        click.echo(f"    {c.name:30}  {c.summary}{flag_str}")
+
+
+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
+    ``roam.commands.cmd_*``.
+    """
+    import importlib
+
+    decorated_modules = [
+        "roam.commands.cmd_critique",
+        "roam.commands.cmd_preflight",
+        "roam.commands.cmd_understand",
+        "roam.commands.cmd_permit",
+        "roam.commands.cmd_postmortem",
+        "roam.commands.cmd_article_12_check",
+    ]
+    for mod in decorated_modules:
+        try:
+            importlib.import_module(mod)
+        except Exception:
+            # Best-effort; if a command module fails to import, skip it
+            pass