argus-code-review 0.2.11__tar.gz → 0.3.0__tar.gz

{argus_code_review-0.2.11 → argus_code_review-0.3.0}/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-13
+
+### Added
+
+- Scope gate: before the early verifier and preflight (including incremental and lite rounds), a new `pr-review-scope` prompt splits the full pinned PR (`merge-base..head`) into independently mergeable behaviors. More than one behavior halts with `scope_split`. An unverifiable manifest (overlapping, unknown, or unassigned files, cyclic dependencies, a 300-file listing, an oversized or indeterminate input, or any gate error) halts with `scope_unverified`.
+- Workload halts: a plan that needs more reviewers than `ARGUS_REVIEWER_DISPATCH_BUDGET` (default 16, range 3-50) halts with `dispatch_budget_exceeded` before any reviewer starts. More than 50 gap-fill reviewers halts with `gap_fill_cap_exceeded`.
+- `ReviewResponse.scope` (pipeline-generated receipt: `base_sha`, `head_sha`, `behaviors`, `rationale`, `override_reason`) and `ReviewResponse.halt` (`code`, `detail`, `head_sha`, `split_suggestions`, `dispatch_count`, `dispatch_budget`). Both are excluded from LLM-generated output. A halt is always `BLOCKING` with `HIGH` risk and has no findings.
+- CLI `--review-override-sha` and `--review-override-reason`: a human exception for `scope_split` and for a plan over the budget (up to the hard ceiling of 50). The SHA must equal the resolved head. It never overrides `scope_unverified` or `gap_fill_cap_exceeded`.
+
+### Changed
+
+- The fan-out ceiling of 50 reviewers no longer truncates the plan or the gap-fill list; exceeding it halts the review.
+- A halted round is stored with `verdict = NULL` and `current_stage = completed`, so it never becomes the prior round: the last reviewed SHA and round count do not advance. The HTTP storage client now skips `verdict = null` rounds like the SQL backends. No schema migration.
+- `--commit-status` posts every outcome to the reviewed head (`halt.head_sha` or `scope.head_sha`) instead of re-reading the live head. The scope gate and bench guard share one merge base pinned in `fetch_diff`; an unpinnable base, an empty manifest for a non-empty diff, an empty-file behavior, or untrimmed titles halt `scope_unverified`.
+- `ReviewResponse` JSON schema gains `scope` and `halt` (golden snapshot updated). The stderr summary block is unchanged.
+
 ## [0.2.11] - 2026-10-12
 
 ### Fixed
@@ -407,7 +423,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   packaged set.
 - `argus --version`, `argus prompts list`, and `argus prompts export`.
 
-[Unreleased]: https://github.com/redesignhealth/argus-review/compare/v0.2.11...HEAD
+[Unreleased]: https://github.com/redesignhealth/argus-review/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/redesignhealth/argus-review/compare/v0.2.11...v0.3.0
 [0.2.11]: https://github.com/redesignhealth/argus-review/compare/v0.2.10...v0.2.11
 [0.2.10]: https://github.com/redesignhealth/argus-review/compare/v0.2.9...v0.2.10
 [0.2.9]: https://github.com/redesignhealth/argus-review/compare/v0.2.8...v0.2.9

{argus_code_review-0.2.11 → argus_code_review-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: argus-code-review
-Version: 0.2.11
+Version: 0.3.0
 Summary: Self-orchestrated PR review agent using LangGraph + Claude Agent SDK
 Project-URL: Repository, https://github.com/redesignhealth/argus-review
 Project-URL: Issues, https://github.com/redesignhealth/argus-review/issues
@@ -137,10 +137,46 @@ consolidates every finding into one review with a verdict and severity
 tags.
 
 ```
-fetch_diff → plan → [system reviewers ‖ specialists ‖ cross-cutting] (parallel)
+fetch_diff → scope_gate → plan → [system reviewers ‖ specialists ‖ cross-cutting] (parallel)
            → check_coverage → (fill_gaps if needed) → write_review → persist
 ```
 
+### Scope and workload halts
+
+Before dispatching reviewer sessions, Argus checks the whole PR (merge base to
+head, on every round, including incremental and lite rounds). If the PR
+contains more than one independently mergeable behavior, or Argus cannot
+verify its scope, the review halts with a `BLOCKING` verdict, `HIGH` risk,
+and no findings. The same happens when the plan needs more reviewers than
+`ARGUS_REVIEWER_DISPATCH_BUDGET` (default 16, range 3-50), or when more
+than 50 gap-fill reviewers are needed. The response carries a `halt`
+object with one of these codes: `scope_split`, `scope_unverified`,
+`dispatch_budget_exceeded`, `gap_fill_cap_exceeded`. A successful review
+carries a `scope` receipt pinned to the reviewed head SHA.
+
+A halted round is not a reviewed round: it is stored with a null verdict,
+so the next run still diffs from the last reviewed SHA. Argus does not
+revoke approvals issued before this guard was enabled, including stored
+approvals for the same SHA. External merge gates must reject the latest
+halt outcome instead of accepting any historical `APPROVE` row.
+
+A human can authorize a multi-behavior PR, or a plan over the budget (up to 50
+reviewers), for one exact head:
+
+```bash
+argus review owner/repo --pr 123 \
+  --review-override-sha HEAD_SHA \
+  --review-override-reason "why this PR stays together"
+```
+
+Both flags are required together. The SHA must equal the head Argus
+resolves, or the run fails before it spends anything (with `--sha`,
+pass the full 40-character SHA). The reason (1-500
+characters) is stored in `scope.override_reason`. These flags exist only
+on the CLI, never on the API request. Agents and skills must not add
+them automatically. They never override `scope_unverified` or
+`gap_fill_cap_exceeded`.
+
 Full design rationale is in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
 
 ## Getting started
@@ -351,7 +387,7 @@ details are in [`docs/STORAGE.md`](docs/STORAGE.md).
 
 ## Adapting Argus to your team
 
-Argus ships with a full set of production review prompts — 20 files, one
+Argus ships with a full set of production review prompts — 21 files, one
 per reviewer role — rather than a thin default. Adapting them to your team
 is the main lever for making Argus *yours*.
 

{argus_code_review-0.2.11 → argus_code_review-0.3.0}/README.md

@@ -86,10 +86,46 @@ consolidates every finding into one review with a verdict and severity
 tags.
 
 ```
-fetch_diff → plan → [system reviewers ‖ specialists ‖ cross-cutting] (parallel)
+fetch_diff → scope_gate → plan → [system reviewers ‖ specialists ‖ cross-cutting] (parallel)
            → check_coverage → (fill_gaps if needed) → write_review → persist
 ```
 
+### Scope and workload halts
+
+Before dispatching reviewer sessions, Argus checks the whole PR (merge base to
+head, on every round, including incremental and lite rounds). If the PR
+contains more than one independently mergeable behavior, or Argus cannot
+verify its scope, the review halts with a `BLOCKING` verdict, `HIGH` risk,
+and no findings. The same happens when the plan needs more reviewers than
+`ARGUS_REVIEWER_DISPATCH_BUDGET` (default 16, range 3-50), or when more
+than 50 gap-fill reviewers are needed. The response carries a `halt`
+object with one of these codes: `scope_split`, `scope_unverified`,
+`dispatch_budget_exceeded`, `gap_fill_cap_exceeded`. A successful review
+carries a `scope` receipt pinned to the reviewed head SHA.
+
+A halted round is not a reviewed round: it is stored with a null verdict,
+so the next run still diffs from the last reviewed SHA. Argus does not
+revoke approvals issued before this guard was enabled, including stored
+approvals for the same SHA. External merge gates must reject the latest
+halt outcome instead of accepting any historical `APPROVE` row.
+
+A human can authorize a multi-behavior PR, or a plan over the budget (up to 50
+reviewers), for one exact head:
+
+```bash
+argus review owner/repo --pr 123 \
+  --review-override-sha HEAD_SHA \
+  --review-override-reason "why this PR stays together"
+```
+
+Both flags are required together. The SHA must equal the head Argus
+resolves, or the run fails before it spends anything (with `--sha`,
+pass the full 40-character SHA). The reason (1-500
+characters) is stored in `scope.override_reason`. These flags exist only
+on the CLI, never on the API request. Agents and skills must not add
+them automatically. They never override `scope_unverified` or
+`gap_fill_cap_exceeded`.
+
 Full design rationale is in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
 
 ## Getting started
@@ -300,7 +336,7 @@ details are in [`docs/STORAGE.md`](docs/STORAGE.md).
 
 ## Adapting Argus to your team
 
-Argus ships with a full set of production review prompts — 20 files, one
+Argus ships with a full set of production review prompts — 21 files, one
 per reviewer role — rather than a thin default. Adapting them to your team
 is the main lever for making Argus *yours*.
 

{argus_code_review-0.2.11 → argus_code_review-0.3.0}/argus/cli.py

@@ -225,13 +225,22 @@ def _check_settings(settings: "Settings") -> None:
         sys.exit(1)
 
 
-async def run(request: "ReviewRequest") -> "ReviewResponse":
+async def run(
+    request: "ReviewRequest",
+    review_override_sha: str | None = None,
+    review_override_reason: str | None = None,
+) -> "ReviewResponse":
     """Run the review pipeline (storage backend resolved automatically:
     Postgres if ``ARGUS_DB_URL`` is set, HTTP shim if the storage URLs are
     set, else local SQLite)."""
     from argus.graph import run_review
 
-    return await run_review(request, flow_run_id=None)
+    return await run_review(
+        request,
+        flow_run_id=None,
+        review_override_sha=review_override_sha,
+        review_override_reason=review_override_reason,
+    )
 
 
 # Sentinel distinguishing "--specialist-model/--frontier-model not passed at
@@ -337,6 +346,23 @@ def _add_review_args(parser: argparse.ArgumentParser) -> None:
             "success iff verdict is APPROVE). Same token rules as --post."
         ),
     )
+    parser.add_argument(
+        "--review-override-sha",
+        dest="review_override_sha",
+        default=None,
+        help=(
+            "Human exception: allow a multi-behavior PR or a reviewer plan over the dispatch "
+            "budget (up to the hard ceiling of 50) to proceed. Must equal the 40-character "
+            "lowercase HEAD SHA being reviewed, and needs --review-override-reason. Never "
+            "overrides an unverified scope or the gap-fill cap."
+        ),
+    )
+    parser.add_argument(
+        "--review-override-reason",
+        dest="review_override_reason",
+        default=None,
+        help="Reason for --review-override-sha (1-500 characters); recorded in the scope receipt.",
+    )
     parser.add_argument(
         "--no-prompt-overrides",
         action="store_true",
@@ -457,6 +483,12 @@ def _validate_review_args(parser: argparse.ArgumentParser, args: argparse.Namesp
     """Cross-flag validation that argparse's own declarative options can't express."""
     if args.post and args.sha and not args.pr:
         parser.error("--post requires --pr (a PR to comment on); --sha alone has nowhere to post")
+    from argus.scope import validate_override
+
+    try:
+        validate_override(args.review_override_sha, args.review_override_reason)
+    except ValueError as exc:
+        parser.error(str(exc))
 
 
 def _check_prerequisites() -> None:
@@ -545,7 +577,9 @@ def _post_review(repo: str, args: argparse.Namespace, response: "ReviewResponse"
             sys.exit(1)
 
     if args.commit_status:
-        sha = args.sha
+        # Post to the head that was reviewed; a re-read head could approve an unreviewed commit.
+        pinned = response.halt or response.scope
+        sha = pinned.head_sha if pinned else args.sha
         if not sha and args.pr:
             pr = client.get_pull_request(repo, args.pr)
             sha = pr["head_sha"]
@@ -553,7 +587,11 @@ def _post_review(repo: str, args: argparse.Namespace, response: "ReviewResponse"
             logger.error("--commit-status could not resolve a head SHA (need --pr or --sha)")
             sys.exit(1)
         state = "success" if response.verdict.value == "APPROVE" else "failure"
-        description = f"Argus: {response.verdict.value} ({response.risk_level.value} risk)"
+        description = (
+            f"Argus: HALT {response.halt.code}"
+            if response.halt
+            else f"Argus: {response.verdict.value} ({response.risk_level.value} risk)"
+        )
         try:
             client.set_commit_status(repo, sha, state, description)
         except Exception as exc:  # noqa: BLE001 — surface any GitHub API error clearly
@@ -633,7 +671,13 @@ def _run_review(parser: argparse.ArgumentParser, args: argparse.Namespace) -> No
 
     start = time.monotonic()
     try:
-        response = asyncio.run(run(request))
+        response = asyncio.run(
+            run(
+                request,
+                review_override_sha=args.review_override_sha,
+                review_override_reason=args.review_override_reason,
+            )
+        )
     except HistoryBackendConnectivityError as exc:
         # Same clean-exit treatment as _check_settings' missing-secrets
         # case -- a bad ARGUS_DB_URL/ARGUS_HISTORY_DB_PATH is a config

{argus_code_review-0.2.11 → argus_code_review-0.3.0}/argus/config.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 from functools import lru_cache
 
+from pydantic import Field
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 # Single source of truth for the reviewer-subprocess wall-clock budget.
@@ -60,6 +61,10 @@ class Settings(BaseSettings):
             name the way prompts are, so there's nothing to merge. Only
             consulted when the ``prechecks`` extra is installed; see
             ``argus.precheck``.
+        ARGUS_REVIEWER_DISPATCH_BUDGET: Maximum reviewers one round may dispatch
+            (system groups, their specialists, plus 2 always-on). Default 16,
+            allowed 3-50. A plan over the budget halts with
+            ``dispatch_budget_exceeded``; the hard ceiling of 50 never moves.
         ARGUS_STOCK_SEMGREP_PACKS: Comma-separated semgrep registry pack IDs
             (e.g. ``"p/secrets"``) to run alongside (or instead of) a custom
             ``ARGUS_RULES_DIR`` -- unlike a local rules directory, each pack
@@ -189,6 +194,8 @@ class Settings(BaseSettings):
 
     ARGUS_SESSION_TIMEOUT: int = DEFAULT_ARGUS_SESSION_TIMEOUT_S
 
+    ARGUS_REVIEWER_DISPATCH_BUDGET: int = Field(16, ge=3, le=50)
+
     ARGUS_BENCH_FILE: str | None = None
     ARGUS_NO_BENCH_OVERRIDES: bool = False