feat: add lightweight CI gate and stdin diff support

Author: Small-fish-QAQ

examples/skills_code_review_agent/README.md

@@ -7,9 +7,11 @@ reports. When `--db-path` is provided, it also persists the review task,
 findings, report metadata, sandbox run metadata, and filter decisions into
 SQLite.
 
-It intentionally does not call an LLM, remote sandbox, or SDK core extension.
-The sandbox runner in this example is a fake dry-run runner: it records what
-would have happened, but never executes untrusted code.
+This is a lightweight deterministic baseline, not a full sandbox/scanner
+implementation. It intentionally does not call an LLM, remote sandbox, Docker,
+Cube, E2B, external scanner, or SDK core extension. The sandbox runner in this
+example is a fake dry-run runner: it records what would have happened, but
+never executes untrusted code.
 
 ## Run
 
@@ -33,6 +35,36 @@ You can also run the clean fixture:
 python examples/skills_code_review_agent/run_agent.py --diff-file examples/skills_code_review_agent/fixtures/clean.diff --output-dir examples/skills_code_review_agent/output_clean --dry-run
 ```
 
+## Run From Stdin
+
+`--diff-file -` reads a unified diff from stdin and records the report input as
+`<stdin>`:
+
+```bash
+git diff | python examples/skills_code_review_agent/run_agent.py --diff-file - --output-dir examples/skills_code_review_agent/output --dry-run
+```
+
+## CI Failure Gate
+
+By default the command exits with `0` even when findings are present. Use
+`--fail-on-severity` to make a lightweight CI gate:
+
+```bash
+python examples/skills_code_review_agent/run_agent.py --diff-file examples/skills_code_review_agent/fixtures/security.diff --output-dir examples/skills_code_review_agent/output --dry-run --fail-on-severity high
+```
+
+Values are `never`, `low`, `medium`, and `high`. For example, `medium` fails on
+medium or high findings, while `high` fails only on high findings.
+
+## List Rules
+
+```bash
+python examples/skills_code_review_agent/run_agent.py --list-rules
+```
+
+This prints the deterministic rule id, category, default severity, description,
+and known limitations without reading a diff.
+
 ## Run With SQLite
 
 ```bash
@@ -70,8 +102,9 @@ python -m pytest examples/skills_code_review_agent/tests
 
 The tests run only local parsing, rules, redaction, report generation, and
 dedupe checks, fake sandbox status, filter decisions, telemetry summaries, and
-SQLite persistence. They do not call an LLM, Docker, Cube, remote network, or
-any external service.
+SQLite persistence. They also cover the lightweight CI failure gate, stdin diff
+input, and rule listing. They do not call an LLM, Docker, Cube, remote network,
+external scanners, or any external service.
 
 ## Fixtures
 
@@ -95,6 +128,9 @@ any external service.
   - `open(...)` without `with`
 - Redacts likely API keys, tokens, secrets, and passwords before writing reports.
 - Produces `review_report.json` and `review_report.md`.
+- Supports reading a unified diff from stdin with `--diff-file -`.
+- Supports a lightweight exit-code gate with `--fail-on-severity`.
+- Prints rule metadata with `--list-rules`.
 - Optionally persists review tasks, findings, and report metadata to SQLite.
 - Records minimal filter decisions: `allow`, `deny`, or `needs_human_review`.
 - Records a fake dry-run sandbox result without executing untrusted code.
@@ -117,6 +153,7 @@ without changing the report and storage shape introduced here.
 
 - Real LLM review.
 - Real remote sandbox or container execution.
+- External scanner integration such as Bandit, Ruff, detect-secrets, or Semgrep.
 - SDK core integration.
 - Production-grade filter governance and telemetry export.
 - Multi-agent orchestration.

examples/skills_code_review_agent/agent/rules.py

@@ -26,6 +26,44 @@
 _BROAD_EXCEPT_RE = re.compile(r"^\s*except\s+Exception(?:\s+as\s+\w+)?\s*:")
 _OPEN_CALL_RE = re.compile(r"\bopen\s*\(")
 
+RULES_MANIFEST = [
+    {
+        "id": "static-rule:hardcoded-secret",
+        "category": "secret",
+        "default_severity": "high",
+        "description": "Flags added lines that appear to assign hardcoded API keys, tokens, secrets, or passwords.",
+        "limitations": "Regex-based and line-oriented; it can miss split secrets and may flag synthetic test data.",
+    },
+    {
+        "id": "static-rule:sql-string-concat",
+        "category": "sql-injection",
+        "default_severity": "high",
+        "description": "Flags SQL statements that appear to use string interpolation, formatting, or concatenation.",
+        "limitations": "Does not parse Python AST or validate actual database driver parameter usage.",
+    },
+    {
+        "id": "static-rule:http-timeout",
+        "category": "network-timeout",
+        "default_severity": "medium",
+        "description": "Flags requests/httpx calls on one added line when no explicit timeout= argument is present.",
+        "limitations": "Only handles simple single-line calls and cannot resolve wrapper defaults.",
+    },
+    {
+        "id": "static-rule:broad-except",
+        "category": "error-handling",
+        "default_severity": "medium/high",
+        "description": "Flags broad except Exception handlers, escalating when the next added line swallows the error.",
+        "limitations": "Line-oriented; it does not build a control-flow graph or inspect existing surrounding code.",
+    },
+    {
+        "id": "static-rule:open-without-context-manager",
+        "category": "resource-lifecycle",
+        "default_severity": "medium",
+        "description": "Flags simple open(...) usage that is not introduced with a with statement.",
+        "limitations": "Does not track close() calls across later lines or helper abstractions.",
+    },
+]
+
 
 def _finding(
     *,

examples/skills_code_review_agent/run_agent.py

@@ -10,6 +10,7 @@
 from __future__ import annotations
 
 import argparse
+import sys
 import time
 from pathlib import Path
 from typing import Sequence
@@ -18,12 +19,20 @@
 from agent.filtering import evaluate_filter_decision
 from agent.report import build_report
 from agent.report import write_reports
+from agent.rules import RULES_MANIFEST
 from agent.rules import run_static_rules
 from agent.sandbox import DryRunSandboxRunner
 from agent.storage import persist_review
 from agent.telemetry import build_telemetry_summary
 
 
+_SEVERITY_RANK = {
+    "low": 1,
+    "medium": 2,
+    "high": 3,
+}
+
+
 def _resolve_path(raw: str) -> Path:
     path = Path(raw).expanduser()
     if path.is_absolute():
@@ -35,12 +44,39 @@ def _default_diff_path() -> str:
     return str(Path(__file__).resolve().parent / "fixtures" / "security.diff")
 
 
+def _read_diff(raw: str) -> tuple[str, str, str]:
+    if raw == "-":
+        return "<stdin>", "<stdin>", sys.stdin.read()
+
+    diff_file = _resolve_path(raw)
+    if not diff_file.exists():
+        raise FileNotFoundError(f"diff file not found: {diff_file}")
+    return str(diff_file), raw, diff_file.read_text(encoding="utf-8")
+
+
+def _print_rules() -> None:
+    print("Deterministic rules")
+    for rule in RULES_MANIFEST:
+        print(f"- {rule['id']}")
+        print(f"  category: {rule['category']}")
+        print(f"  default severity: {rule['default_severity']}")
+        print(f"  description: {rule['description']}")
+        print(f"  limitations: {rule['limitations']}")
+
+
+def _failure_gate_triggered(findings: Sequence[object], threshold: str) -> bool:
+    if threshold == "never":
+        return False
+    minimum = _SEVERITY_RANK[threshold]
+    return any(_SEVERITY_RANK.get(getattr(finding, "severity", ""), 0) >= minimum for finding in findings)
+
+
 def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
     parser = argparse.ArgumentParser(description="Run deterministic code review over a unified diff.")
     parser.add_argument(
         "--diff-file",
         default=_default_diff_path(),
-        help="Path to a unified diff file. Defaults to fixtures/security.diff.",
+        help="Path to a unified diff file, or '-' to read from stdin. Defaults to fixtures/security.diff.",
     )
     parser.add_argument(
         "--output-dir",
@@ -57,23 +93,34 @@ def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
         default="",
         help="Optional SQLite database path for persisting review tasks, findings, and reports.",
     )
+    parser.add_argument(
+        "--fail-on-severity",
+        choices=("never", "low", "medium", "high"),
+        default="never",
+        help="Exit with status 1 when findings meet or exceed this severity. Defaults to never.",
+    )
+    parser.add_argument(
+        "--list-rules",
+        action="store_true",
+        help="Print deterministic rule metadata and exit without reading a diff.",
+    )
     return parser.parse_args(argv)
 
 
 def main(argv: Sequence[str] | None = None) -> int:
     started = time.perf_counter()
     args = parse_args(argv)
-    diff_file = _resolve_path(args.diff_file)
+    if args.list_rules:
+        _print_rules()
+        return 0
+
     output_dir = _resolve_path(args.output_dir)
     db_path = _resolve_path(args.db_path) if args.db_path else None
-
-    if not diff_file.exists():
-        raise FileNotFoundError(f"diff file not found: {diff_file}")
-
-    diff_text = diff_file.read_text(encoding="utf-8")
+    diff_display, report_diff_file, diff_text = _read_diff(args.diff_file)
     parsed_diff = parse_unified_diff(diff_text)
     filter_decision = evaluate_filter_decision(diff_text, parsed_diff)
     findings = run_static_rules(parsed_diff.changed_lines)
+    failure_gate_triggered = _failure_gate_triggered(findings, args.fail_on_severity)
     sandbox_run = DryRunSandboxRunner().run(
         files=parsed_diff.files,
         findings=findings,
@@ -88,7 +135,7 @@ def main(argv: Sequence[str] | None = None) -> int:
         duration_ms=duration_ms,
     )
     report = build_report(
-        diff_file=args.diff_file,
+        diff_file=report_diff_file,
         files=parsed_diff.files,
         findings=findings,
         dry_run=args.dry_run,
@@ -111,17 +158,23 @@ def main(argv: Sequence[str] | None = None) -> int:
     low_count = report["summary"]["severity_counts"].get("low", 0)
 
     print("Skills code review dry-run complete")
-    print(f"Diff file: {diff_file}")
+    print(f"Diff file: {diff_display}")
     print(f"Changed files: {len(parsed_diff.files)}")
     print(f"Findings: high={high_count} medium={medium_count} low={low_count}")
     print(f"Filter decision: {filter_decision.decision} ({filter_decision.reason})")
     print(f"Sandbox status: {sandbox_run.status}")
+    if args.fail_on_severity == "never":
+        print("Failure gate: disabled (--fail-on-severity never)")
+    elif failure_gate_triggered:
+        print(f"Failure gate: triggered (--fail-on-severity {args.fail_on_severity})")
+    else:
+        print(f"Failure gate: passed (--fail-on-severity {args.fail_on_severity})")
     print(f"JSON report: {json_path}")
     print(f"Markdown report: {md_path}")
     if db_path is not None:
         print(f"Database: {db_path}")
         print(f"Task ID: {task_id}")
-    return 0
+    return 1 if failure_gate_triggered else 0
 
 
 if __name__ == "__main__":

examples/skills_code_review_agent/tests/test_static_review.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import io
+import json
 import sqlite3
 from pathlib import Path
 
@@ -15,6 +17,7 @@
 from agent.sandbox import DryRunSandboxRunner
 from agent.storage import persist_review
 from agent.telemetry import build_telemetry_summary
+from run_agent import main as run_agent_main
 
 
 EXAMPLE_ROOT = Path(__file__).resolve().parents[1]
@@ -178,3 +181,72 @@ def test_sqlite_persists_sandbox_and_filter_rows(tmp_path: Path) -> None:
     assert filter_count == 1
     assert sandbox_status == "completed"
     assert filter_decision == "allow"
+
+
+def test_fail_on_severity_high_returns_nonzero(tmp_path: Path, capsys) -> None:
+    exit_code = run_agent_main(
+        [
+            "--diff-file",
+            str(FIXTURES / "security.diff"),
+            "--output-dir",
+            str(tmp_path),
+            "--dry-run",
+            "--fail-on-severity",
+            "high",
+        ]
+    )
+    captured = capsys.readouterr()
+
+    assert exit_code == 1
+    assert "Failure gate: triggered (--fail-on-severity high)" in captured.out
+
+
+def test_fail_on_severity_never_returns_zero(tmp_path: Path, capsys) -> None:
+    exit_code = run_agent_main(
+        [
+            "--diff-file",
+            str(FIXTURES / "security.diff"),
+            "--output-dir",
+            str(tmp_path),
+            "--dry-run",
+            "--fail-on-severity",
+            "never",
+        ]
+    )
+    captured = capsys.readouterr()
+
+    assert exit_code == 0
+    assert "Failure gate: disabled (--fail-on-severity never)" in captured.out
+
+
+def test_list_rules_outputs_rule_metadata(capsys) -> None:
+    exit_code = run_agent_main(["--list-rules", "--diff-file", "does-not-exist.diff"])
+    captured = capsys.readouterr()
+
+    assert exit_code == 0
+    assert "Deterministic rules" in captured.out
+    assert "static-rule:hardcoded-secret" in captured.out
+    assert "category: secret" in captured.out
+    assert "limitations:" in captured.out
+
+
+def test_diff_file_stdin_reads_unified_diff(tmp_path: Path, monkeypatch, capsys) -> None:
+    diff_text = (FIXTURES / "missing_timeout.diff").read_text(encoding="utf-8")
+    monkeypatch.setattr("sys.stdin", io.StringIO(diff_text))
+
+    exit_code = run_agent_main(
+        [
+            "--diff-file",
+            "-",
+            "--output-dir",
+            str(tmp_path),
+            "--dry-run",
+        ]
+    )
+    captured = capsys.readouterr()
+    report = json.loads((tmp_path / "review_report.json").read_text(encoding="utf-8"))
+
+    assert exit_code == 0
+    assert "Diff file: <stdin>" in captured.out
+    assert report["summary"]["diff_file"] == "<stdin>"
+    assert report["summary"]["category_counts"]["network-timeout"] == 1