feat: codebase scope review

app/AGENTS.md

@@ -26,7 +26,7 @@ The call chain follows four conceptual layers:
 
 1. **Receive** — `commands/webhook/main.py` (webhooks), `commands/` (CLI/CI).
 2. **Prepare** — `workspace/setup.py::prepare_job_event()` resolves clone URLs and branches; `commands/webhook/jobs/runner/process.py` wraps with error handling and queue management.
-3. **Orchestrate** — `review/reviewer.py` (business logic: diff fetching, PR metadata fetching, prompt building, sub-agent configuration, output parsing).
+3. **Orchestrate** — `review/reviewer.py` (business logic: diff fetching, PR metadata fetching, prompt building, sub-agent configuration, output parsing). `ReviewScope.CODEBASE` skips all platform API calls (diff/comments/metadata), skips diff-line filtering, and uses a codebase-review prompt header — intended for whole-repo audit passes that have no associated PR.
 4. **Invoke** — `agent/invoke.py` provides agent execution with explicit conversation lifecycle (`prepare_conversation`, `invoke_agent`, `save_conversation`).
 
 ## Agent runner selection

app/nominal_code/commands/webhook/jobs/dispatch.py

@@ -7,6 +7,7 @@
 from nominal_code.commands.webhook.jobs.handler import JobHandler
 from nominal_code.commands.webhook.jobs.payload import JobPayload
 from nominal_code.platforms.base import CommentEvent
+from nominal_code.review.reviewer import ReviewScope
 from nominal_code.workspace.setup import prepare_job_event
 
 if TYPE_CHECKING:
@@ -60,6 +61,8 @@ async def execute_job(
     conversation_store: ConversationStore | None = None,
     pre_cloned: bool = False,
     context: str = "",
+    scope: ReviewScope = ReviewScope.PR,
+    workspace_path: str | None = None,
 ) -> JobResult:
     """
     Execute a review job.
@@ -77,6 +80,10 @@ async def execute_job(
         pre_cloned (bool): When True, the repository was pre-cloned by
             an external process and clone URL resolution is skipped.
         context (str): Pre-review context to include in the user message.
+        scope (ReviewScope): Whether this is a PR diff review or a
+            whole-repository codebase review.
+        workspace_path (str): Pre-existing workspace path. Required when
+            ``scope`` is ``ReviewScope.CODEBASE``.
 
     Returns:
         JobResult: The execution result.
@@ -100,6 +107,8 @@ async def execute_job(
         conversation_store=conversation_store,
         namespace=job.namespace,
         context=context,
+        scope=scope,
+        workspace_path=workspace_path,
     )
 
     return JobResult(review_result=review_result)

app/nominal_code/commands/webhook/jobs/handler.py

@@ -2,6 +2,8 @@
 
 from typing import TYPE_CHECKING, Protocol
 
+from nominal_code.review.reviewer import ReviewScope, run_and_post_review
+
 if TYPE_CHECKING:
     from nominal_code.config import Config
     from nominal_code.conversation.base import ConversationStore
@@ -31,6 +33,8 @@ async def handle_review(
         conversation_store: ConversationStore | None = None,
         namespace: str = "",
         context: str = "",
+        scope: ReviewScope = ReviewScope.PR,
+        workspace_path: str | None = None,
     ) -> ReviewResult:
         """
         Execute a code review and post results.
@@ -44,6 +48,10 @@ async def handle_review(
                 conversation continuity.
             namespace (str): Logical namespace for conversation key isolation.
             context (str): Pre-review context to include in the user message.
+            scope (ReviewScope): Whether this is a PR diff review or a
+                whole-repository codebase review.
+            workspace_path (str): Pre-existing workspace path. Required when
+                ``scope`` is ``ReviewScope.CODEBASE``.
 
         Returns:
             ReviewResult: The review result with findings and summary.
@@ -66,6 +74,8 @@ async def handle_review(
         conversation_store: ConversationStore | None = None,
         namespace: str = "",
         context: str = "",
+        scope: ReviewScope = ReviewScope.PR,
+        workspace_path: str | None = None,
     ) -> ReviewResult:
         """
         Delegate to ``run_and_post_review``.
@@ -79,13 +89,15 @@ async def handle_review(
                 conversation continuity.
             namespace (str): Logical namespace for conversation key isolation.
             context (str): Pre-review context to include in the user message.
+            scope (ReviewScope): Whether this is a PR diff review or a
+                whole-repository codebase review.
+            workspace_path (str): Pre-existing workspace path. Required when
+                ``scope`` is ``ReviewScope.CODEBASE``.
 
         Returns:
             ReviewResult: The review result with findings and summary.
         """
 
-        from nominal_code.review.reviewer import run_and_post_review
-
         return await run_and_post_review(
             event=event,
             prompt=prompt,
@@ -94,4 +106,6 @@ async def handle_review(
             conversation_store=conversation_store,
             namespace=namespace,
             context=context,
+            scope=scope,
+            workspace_path=workspace_path,
         )

app/nominal_code/commands/webhook/jobs/main.py

@@ -18,6 +18,7 @@
 from nominal_code.models import ProviderName
 from nominal_code.platforms import build_platform
 from nominal_code.platforms.base import Platform, PlatformName
+from nominal_code.review.reviewer import ReviewScope
 
 _env: Env = Env()
 
@@ -27,6 +28,8 @@
 async def run_job_main(
     pre_cloned: bool = False,
     context: str = "",
+    scope: ReviewScope = ReviewScope.PR,
+    workspace_path: str | None = None,
 ) -> JobResult | None:
     """
     Entry point for the ``run-job`` CLI subcommand.
@@ -39,6 +42,10 @@ async def run_job_main(
         pre_cloned (bool): When True, the repository was pre-cloned by
             an external process and clone URL resolution is skipped.
         context (str): Pre-review context to include in the user message.
+        scope (ReviewScope): Whether this is a PR diff review or a
+            whole-repository codebase review.
+        workspace_path (str): Pre-existing workspace path. Required when
+            ``scope`` is ``ReviewScope.CODEBASE``.
 
     Returns:
         JobResult | None: The job result on success, or ``None`` on
@@ -85,6 +92,8 @@ async def run_job_main(
         conversation_store=conversation_store,
         pre_cloned=pre_cloned,
         context=context,
+        scope=scope,
+        workspace_path=workspace_path,
     )
 
     succeeded: bool = result is not None
@@ -101,6 +110,8 @@ async def _run_job(
     conversation_store: ConversationStore | None = None,
     pre_cloned: bool = False,
     context: str = "",
+    scope: ReviewScope = ReviewScope.PR,
+    workspace_path: str | None = None,
 ) -> JobResult | None:
     """
     Execute a job via the unified dispatch pipeline.
@@ -114,6 +125,10 @@ async def _run_job(
             for conversation continuity.
         pre_cloned (bool): When True, skip clone URL resolution.
         context (str): Pre-review context to include in the user message.
+        scope (ReviewScope): Whether this is a PR diff review or a
+            whole-repository codebase review.
+        workspace_path (str): Pre-existing workspace path. Required when
+            ``scope`` is ``ReviewScope.CODEBASE``.
 
     Returns:
         JobResult | None: The job result on success, or ``None`` on
@@ -136,6 +151,8 @@ async def _run_job(
             conversation_store=conversation_store,
             pre_cloned=pre_cloned,
             context=context,
+            scope=scope,
+            workspace_path=workspace_path,
         )
     except Exception:
         logger.exception(

app/nominal_code/review/prompts.py

@@ -22,6 +22,44 @@
 MAX_COMMIT_MESSAGES: int = 20
 
 
+def build_codebase_reviewer_prompt(
+    event: PullRequestEvent,
+    user_prompt: str,
+    context: str = "",
+) -> str:
+    """
+    Build a prompt for a whole-repository review (no diff context).
+
+    Used when ``scope`` is ``ReviewScope.CODEBASE``. Produces a header
+    that identifies the repo and branch without referencing a PR number
+    or diff. The LLM is expected to explore the workspace via its tools.
+
+    Args:
+        event (PullRequestEvent): Event carrying the repo name and branch.
+        user_prompt (str): Optional caller-supplied instructions.
+        context (str): Pre-review exploration notes to insert before
+            the review instruction.
+
+    Returns:
+        str: The full prompt to send to the codebase reviewer.
+    """
+
+    parts: list[str] = [
+        f"## Codebase review: {event.repo_full_name}\n\n"
+        f"**Branch**: <{TAG_BRANCH_NAME}>{event.pr_branch}</{TAG_BRANCH_NAME}>"
+    ]
+
+    if user_prompt:
+        parts.append(
+            f"Additional instructions:\n{wrap_tag(TAG_UNTRUSTED_REQUEST, user_prompt)}"
+        )
+
+    if context:
+        parts.append(context)
+
+    return "\n\n".join(parts)
+
+
 def build_reviewer_prompt(
     event: PullRequestEvent,
     user_prompt: str,
@@ -87,8 +125,7 @@ def build_reviewer_prompt(
 
     review_instruction: str = (
         "Review the above changes. Each diff line is annotated with its "
-        "actual line number — use these directly. Call the submit_review "
-        "tool with your complete review.\n\n"
+        "actual line number — use these directly.\n\n"
         "For comments on deleted lines (prefixed with `-` in the diff), "
         'set `"side": "LEFT"`. For additions (`+`) and context lines '
         'omit `side` or use `"RIGHT"`.'