examples: address code-review findings (standards and spec)

Make the sandbox the accepted path. run_review defaults to the auto
runtime, which uses the container sandbox when Docker is available and
the local subprocess sandbox otherwise; in-process becomes an explicit
dev fast-path, and both the selftest and the agent tool run through the
sandbox. The standalone run_checks.py and pipeline/scanners.py are
reconciled to emit identical findings (aligned severity, confidence and
path normalization), enforced by a parity test, so the two paths cannot
drift.

Make failures visible. A missing scanner produces a needs-human-review
finding instead of a silent zero-finding report; the monitoring
tool-call count reflects the scanners that actually ran; and the
persisted review status is derived from the run (blocked, failed, or
completed) rather than always completed.

Correctness and deliverables. File-level findings key on the rule as
well as the category so distinct issues in one category are not
collapsed. The container path's post-processing is extracted into
build_container_result and unit-tested without Docker. The agent CLI
gains a dry-run flag that forces the fake model, the stale run_review
docstring is corrected, and the change adds the committed sample report
and a RULES.md documenting all six categories. yapf and the
trailing-newline fix leave the tree lint-clean.

Updates #92

RELEASE NOTES: NONE

Author: Acture

examples/skills_code_review_agent/README.md

@@ -11,20 +11,26 @@ renders `review_report.json` + `review_report.md`.
 ```bash
 pip install -r requirements.txt
 
-# Review a bundled fixture (dry-run, deterministic — no model needed):
-python run_review.py --fixture 0001_insecure.diff --out-dir /tmp/cr
+# Review a bundled fixture (no model needed). Default runtime is the sandbox
+# (auto -> container if Docker is up, else the local subprocess sandbox):
+python run_review.py --fixture security.diff --out-dir /tmp/cr
 
-# Review your own diff or working tree:
+# Review your own diff, working tree, or an explicit file list:
 python run_review.py --diff-file my.diff
 python run_review.py --repo-path /path/to/repo --no-db
+python run_review.py --files pipeline/engine.py,pipeline/scanners.py
 
 # Scored self-test over the labelled fixtures (detection-rate / false-positive-rate):
 python selftest.py
 
-# Run the review through the LlmAgent (fake model, no API key needed):
-python run_agent.py --fixture 0001_insecure.diff
+# Run the review through the LlmAgent with the fake model (no API key needed):
+python run_agent.py --fixture security.diff --dry-run
 ```
 
+A sample report is committed under [`sample_output/`](./sample_output/); the rule catalog is in
+[`../../skills/code-review/docs/RULES.md`](../../skills/code-review/docs/RULES.md) and the design note
+in [DESIGN.md](./DESIGN.md).
+
 ## How it works
 
 Findings come from **deterministic static scanners**, not the LLM, so results are reproducible and

examples/skills_code_review_agent/agent/agent.py

@@ -3,7 +3,6 @@
 # Copyright (C) 2026 Tencent. All rights reserved.
 #
 # tRPC-Agent-Python is licensed under Apache-2.0.
-
 """Construct the code-review LlmAgent (Skills + tool), used by run_agent.py."""
 from __future__ import annotations
 
@@ -14,15 +13,16 @@
 from .tools import build_review_tool
 
 
-def create_agent() -> LlmAgent:
+def create_agent(dry_run: bool = False) -> LlmAgent:
     """An LlmAgent that reviews a diff by calling the review_code tool, then summarizes.
 
-    The guard Filter (slice 3) attaches on the tool via ``filters_name`` — a TOOL-scoped filter,
-    not on the agent (which resolves in the AGENT namespace and would raise).
+    ``dry_run`` forces the fake model even if an API key is set. The guard Filter attaches on the tool
+    via ``filters_name`` — a TOOL-scoped filter, not on the agent (which resolves in the AGENT
+    namespace and would raise).
     """
     return LlmAgent(
         name="code_review_agent",
-        model=get_model(),
+        model=get_model(force_fake=dry_run),
         instruction=INSTRUCTION,
         tools=[build_review_tool()],
     )

examples/skills_code_review_agent/agent/config.py

@@ -3,7 +3,6 @@
 # Copyright (C) 2026 Tencent. All rights reserved.
 #
 # tRPC-Agent-Python is licensed under Apache-2.0.
-
 """Configuration for the agent path — model selection and defaults."""
 from __future__ import annotations
 
@@ -14,10 +13,10 @@
 from .model import FakeReviewModel
 
 
-def get_model() -> LLMModel:
-    """Return the fake model by default (no API key); a real OpenAI model if one is configured."""
+def get_model(force_fake: bool = False) -> LLMModel:
+    """Fake model by default / when ``force_fake`` (dry-run); a real OpenAI model if a key is set."""
     api_key = os.getenv("TRPC_AGENT_API_KEY")
-    if api_key:
+    if api_key and not force_fake:
         from trpc_agent_sdk.models import OpenAIModel
 
         return OpenAIModel(

examples/skills_code_review_agent/agent/filter.py

@@ -3,7 +3,6 @@
 # Copyright (C) 2026 Tencent. All rights reserved.
 #
 # tRPC-Agent-Python is licensed under Apache-2.0.
-
 """ReviewGuardFilter — the framework enforcement site for the review policy (issue #92, req 7).
 
 A TOOL-scoped filter (``register_tool_filter``): it inspects a tool call's args before the tool

examples/skills_code_review_agent/agent/model.py

@@ -3,7 +3,6 @@
 # Copyright (C) 2026 Tencent. All rights reserved.
 #
 # tRPC-Agent-Python is licensed under Apache-2.0.
-
 """FakeReviewModel — deterministic, no-API-key model for the dry-run agent path (criterion 6/8).
 
 It does not call any LLM. On the first turn it emits a single tool call to ``review_code`` with the

examples/skills_code_review_agent/agent/prompts.py

@@ -3,7 +3,6 @@
 # Copyright (C) 2026 Tencent. All rights reserved.
 #
 # tRPC-Agent-Python is licensed under Apache-2.0.
-
 """System instruction for the code-review agent's LLM finding source."""
 
 INSTRUCTION = ("You are an automated code reviewer. When given a diff, call the `review_code` tool with the "

examples/skills_code_review_agent/pipeline/dedup.py

@@ -3,7 +3,6 @@
 # Copyright (C) 2026 Tencent. All rights reserved.
 #
 # tRPC-Agent-Python is licensed under Apache-2.0.
-
 """Dedup + denoise (issue #92, requirement 6).
 
 - Dedup: at most one finding per (file, line, category); keep the highest-confidence one and mark
@@ -21,6 +20,10 @@
 
 
 def dedup_key(f: Finding) -> str:
+    # File-level findings (line is None) share file+category but are distinct issues — key on the
+    # rule/title too so two different file-level findings in one category don't collapse into one.
+    if f.line is None:
+        return f"{f.file}::{f.category}:{f.rule_id or f.title}"
     return f"{f.file}:{f.line}:{f.category}"
 
 

examples/skills_code_review_agent/pipeline/engine.py

@@ -73,7 +73,7 @@ def run_review(
     repo_path: Optional[str] = None,
     files: Optional[list[str]] = None,
     repo_root: str = ".",
-    runtime: str = "inprocess",
+    runtime: str = "auto",
     sandbox_timeout: float | None = None,
     max_output_bytes: int | None = None,
     policy: ReviewPolicy | None = None,
@@ -93,6 +93,13 @@ def run_review(
     started = time.monotonic()
     exception_dist: dict[str, int] = {}
 
+    # `auto` is the default: sandbox, not in-process. This sync entry can't drive the async container
+    # runtime, so auto resolves to the local subprocess sandbox here; the CLI upgrades auto->container
+    # when Docker is available (see run_review.py / run_review_container). `inprocess` is an opt-in dev
+    # fast-path that must be requested explicitly.
+    if runtime == "auto":
+        runtime = "local"
+
     if diff_text is not None:
         summary, scan_dir = _materialize(diff_text)
         source_type, source_ref = "diff_file", "<diff>"
@@ -157,7 +164,7 @@ def _assemble(task_id, summary, raw, sandbox_runs, source_type, source_ref, star
     monitoring = {
         "total_sec": round(time.monotonic() - started, 3),
         "sandbox_sec": round(sum(r.duration_sec for r in sandbox_runs), 3),
-        "tool_calls": len(scanners.ADAPTERS),
+        "tool_calls": scanners.tool_calls_available(),
         "block_count": len(filter_blocks),
         "finding_count": len(active),
         "severity_dist": severity_dist,

examples/skills_code_review_agent/pipeline/report.py

@@ -3,7 +3,6 @@
 # Copyright (C) 2026 Tencent. All rights reserved.
 #
 # tRPC-Agent-Python is licensed under Apache-2.0.
-
 """Build and render the review report (issue #92, requirement: report with 7 sections).
 
 The 7 sections (findings summary, severity stats, human-review items, Filter-block summary,

examples/skills_code_review_agent/pipeline/sandbox.py

@@ -174,20 +174,41 @@ async def run_container(
                                     timeout=timeout,
                                     limits=WorkspaceResourceLimits(memory_mb=memory_mb)))
         collected = await fs.collect_outputs(ws, WorkspaceOutputSpec(globs=["findings.json"]))
-        findings: list[Finding] = []
-        for cf in getattr(collected, "files", collected) or []:
-            try:
-                findings = parse_findings_json(json.loads(cf.content.decode("utf-8")))
-            except Exception:  # noqa: BLE001
-                continue
-        _, out_bytes = _truncate(run.stdout, max_bytes)
-        _, err_bytes = _truncate(run.stderr, max_bytes)
-        result = SandboxRunResult(script="run_checks.py",
-                                  exit_code=run.exit_code,
-                                  duration_sec=round(time.monotonic() - started, 3),
-                                  timed_out=run.timed_out,
-                                  stdout_bytes=out_bytes,
-                                  stderr_bytes=err_bytes)
-        return findings, result
+        return build_container_result(getattr(collected, "files", collected),
+                                      stdout=run.stdout,
+                                      stderr=run.stderr,
+                                      exit_code=run.exit_code,
+                                      timed_out=run.timed_out,
+                                      duration_sec=time.monotonic() - started,
+                                      max_bytes=max_bytes)
     finally:
         await manager.cleanup(exec_id)
+
+
+def build_container_result(collected_files,
+                           *,
+                           stdout,
+                           stderr,
+                           exit_code,
+                           timed_out,
+                           duration_sec,
+                           max_bytes=MAX_OUTPUT_BYTES) -> tuple[list[Finding], SandboxRunResult]:
+    """Pure post-processing of a container run (parse findings.json + build SandboxRunResult).
+
+    Extracted so the container path's logic is unit-testable without Docker (the Docker-only part is
+    just staging + running the workspace). ``collected_files`` are objects with a ``.content`` bytes attr.
+    """
+    findings: list[Finding] = []
+    for cf in collected_files or []:
+        try:
+            findings = parse_findings_json(json.loads(cf.content.decode("utf-8")))
+        except Exception:  # noqa: BLE001 - a malformed collected file degrades the source, not the task
+            continue
+    _, out_bytes = _truncate(stdout, max_bytes)
+    _, err_bytes = _truncate(stderr, max_bytes)
+    return findings, SandboxRunResult(script="run_checks.py",
+                                      exit_code=exit_code,
+                                      duration_sec=round(duration_sec, 3),
+                                      timed_out=timed_out,
+                                      stdout_bytes=out_bytes,
+                                      stderr_bytes=err_bytes)