@vigolium/piolium 0.0.1

package/skills/audit/scripts/partition_findings.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""
+Route confirmed vs theoretical findings AFTER poc-author has run.
+
+`consolidate_drafts.py` puts every actionable finding in
+`<archon_dir>/findings/<ID>-<slug>/`. poc-author then attempts a PoC for
+each and writes `PoC-Status: executed | theoretical | blocked` back into the
+finding's `draft.md`. This script reads that field and demotes any finding
+that did NOT reach `PoC-Status: executed` into
+`<archon_dir>/findings-theoretical/<ID>-<slug>/` (same directory shape, IDs
+unchanged so cross-references stay stable).
+
+Bucket contract:
+    findings/              -> confirmed, PoC executed (the actionable bucket)
+    findings-theoretical/  -> no PoC / theoretical / blocked, plus the
+                              triage-skipped findings consolidate_drafts.py
+                              already placed there.
+
+The script is idempotent: re-running it never moves an already-`executed`
+finding, and a re-demoted finding overwrites any stale same-ID directory in
+the theoretical bucket. It is a no-op for modes that never build PoCs
+(nothing is `executed`, but those modes simply don't invoke this script).
+
+Usage:
+    partition_findings.py [archon_dir]
+
+archon_dir defaults to "archon". Exit codes:
+    0  success (including "nothing to move")
+    2  usage error / archon_dir missing
+    3  I/O error during partition
+"""
+
+import json
+import os
+import re
+import shutil
+import sys
+from pathlib import Path
+
+FINDING_DIR_RE = re.compile(r"^[CHM]\d+-")
+# Same shape as consolidate_drafts.py's KV_RE, intentionally duplicated:
+# every vendored script under skills/audit/scripts/ is standalone (copied
+# verbatim at install time, no cross-script imports). Keep the two in sync.
+KV_RE = re.compile(r"^([A-Za-z][A-Za-z0-9 _-]*):\s*(.*)$")
+
+
+def read_poc_status(draft_path: Path) -> str:
+    """Return the lowercased PoC-Status value from a finding draft, or "" if
+    absent.
+
+    poc-author writes `PoC-Status:` back into an already-materialised
+    `draft.md` *after* consolidation, so it does not always land inside the
+    strict leading `Key: Value` block (which terminates at the first blank
+    line or `## ` heading). Demoting a genuinely confirmed finding because
+    the field sat one line outside that block is the costly failure
+    direction, so scan the WHOLE file for a `PoC-Status:` line and take the
+    last occurrence (re-runs append an updated value). This matches how
+    finding-writer and merge mode read the field loosely.
+    """
+    if not draft_path.is_file():
+        return ""
+    found = ""
+    try:
+        with draft_path.open() as f:
+            for line in f:
+                m = KV_RE.match(line.rstrip("\n"))
+                if m and m.group(1).strip().lower() == "poc-status":
+                    found = m.group(2).strip().lower()
+    except OSError:
+        pass
+    return found
+
+
+def move_into(src: Path, dest_dir: Path) -> Path:
+    """Move `src` directory into `dest_dir`, replacing any same-named target
+    so the operation is idempotent. Returns the destination path.
+    """
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    target = dest_dir / src.name
+    if target.exists():
+        shutil.rmtree(target)
+    shutil.move(str(src), str(target))
+    return target
+
+
+def partition(archon_dir: Path) -> int:
+    findings_dir = archon_dir / "findings"
+    theoretical_dir = archon_dir / "findings-theoretical"
+
+    kept: list[str] = []
+    moved: list[dict] = []
+
+    if findings_dir.is_dir():
+        for entry in sorted(os.listdir(findings_dir)):
+            folder = findings_dir / entry
+            if not folder.is_dir() or not FINDING_DIR_RE.match(entry):
+                continue
+            status = read_poc_status(folder / "draft.md")
+            if status == "executed":
+                kept.append(entry)
+                continue
+            dest = move_into(folder, theoretical_dir)
+            moved.append(
+                {
+                    "id": entry.split("-", 1)[0],
+                    "dir": entry,
+                    "poc_status": status or "missing",
+                    "to": str(dest),
+                }
+            )
+
+    manifest = {
+        "archon_dir": str(archon_dir),
+        "kept": kept,
+        "moved": moved,
+        "counts": {"kept": len(kept), "moved": len(moved)},
+    }
+    (archon_dir / "findings-draft").mkdir(parents=True, exist_ok=True)
+    (archon_dir / "findings-draft" / "partition-manifest.json").write_text(
+        json.dumps(manifest, indent=2) + "\n"
+    )
+    print(json.dumps(manifest, indent=2))
+    print(
+        f"partition: {len(kept)} confirmed stay in findings/, "
+        f"{len(moved)} demoted to findings-theoretical/ "
+        f"(no PoC / theoretical / blocked)",
+        file=sys.stderr,
+    )
+    return 0
+
+
+def main() -> None:
+    argv = sys.argv[1:]
+    if argv and argv[0] in ("-h", "--help"):
+        print(__doc__)
+        sys.exit(0)
+    if len(argv) > 1:
+        print("usage: partition_findings.py [archon_dir]", file=sys.stderr)
+        sys.exit(2)
+    archon_dir = Path(argv[0]) if argv else Path("archon")
+    if not archon_dir.is_dir():
+        print(f"error: archon dir not found: {archon_dir}", file=sys.stderr)
+        sys.exit(2)
+    try:
+        sys.exit(partition(archon_dir))
+    except OSError as e:
+        print(f"error: I/O failure during partition: {e}", file=sys.stderr)
+        sys.exit(3)
+
+
+if __name__ == "__main__":
+    main()

package/skills/audit/scripts/rg-hotspots.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Fast, noisy-first security hotspot discovery.
+# Goal: find review starting points (sinks and risky APIs), not prove vulns.
+#
+# Usage:
+#   scripts/rg-hotspots.sh            # scan repo from cwd
+#   scripts/rg-hotspots.sh path/      # scan a subdir
+#
+# Tips:
+# - Pipe into a pager: `... | less -R`
+# - Narrow scope for signal: `... api/` or `... src/auth/`
+
+root="${1:-.}"
+
+if ! command -v rg >/dev/null 2>&1; then
+  echo "error: rg (ripgrep) not found in PATH" >&2
+  exit 2
+fi
+
+rg_base=(
+  --no-heading
+  --line-number
+  --hidden
+  --follow
+  --smart-case
+  --glob '!.git/**'
+  --glob '!**/node_modules/**'
+  --glob '!**/dist/**'
+  --glob '!**/build/**'
+  --glob '!**/target/**'
+  --glob '!**/.next/**'
+  --glob '!**/vendor/**'
+  --glob '!**/.venv/**'
+  --glob '!**/venv/**'
+)
+
+section() {
+  echo
+  echo "== $1"
+}
+
+run() {
+  local label="$1"
+  shift
+  section "$label"
+  # `|| true` because some sections will have no matches (not an error).
+  rg "${rg_base[@]}" "$@" "$root" || true
+}
+
+section "RG Hotspots"
+echo "root: $root"
+
+run "Command Execution / Dangerous Eval" \
+  -e 'Runtime\.getRuntime\(\)\.exec' \
+  -e 'ProcessBuilder\s*\(' \
+  -e '\bexec(ute)?\s*\(' \
+  -e '\bsystem\s*\(' \
+  -e '\bpopen\s*\(' \
+  -e 'child_process\.(exec|execSync|spawn|spawnSync)\b' \
+  -e '\bos\.system\b' \
+  -e '\bsubprocess\.(run|Popen|call|check_output)\b' \
+  -e '\beval\s*\(' \
+  -e '\bFunction\s*\(' \
+  -e 'vm\.run(In(New)?Context|InThisContext)\b'
+
+run "Deserialization / Template Injection Primitives" \
+  -e '\bpickle\.loads\b' \
+  -e '\byaml\.load\s*\(' \
+  -e '\bObjectInputStream\b' \
+  -e '\breadObject\s*\(' \
+  -e '\bunserialize\s*\(' \
+  -e '\bMarshal\.load\b' \
+  -e '\bERB\.new\b' \
+  -e '\bnew\s+Template\b' \
+  -e '\bMustache\.' \
+  -e '\bHandlebars\.' \
+  -e '\bEJS\b'
+
+run "SSRF / URL Fetching / HTTP Clients (review call sites)" \
+  -e '\brequests\.(get|post|put|delete|head|patch)\b' \
+  -e '\burllib\.(request|parse)\b' \
+  -e '\bhttpx\.(get|post|Client)\b' \
+  -e '\baxios\.' \
+  -e '\bfetch\s*\(' \
+  -e '\bgot\s*\(' \
+  -e '\bnew\s+URL\s*\(' \
+  -e '\bnet/http\b' \
+  -e '\bhttp\.NewRequest\b' \
+  -e '\bhttp\.Client\b'
+
+run "SQL / Query Construction (review interpolation/concatenation)" \
+  -e '\bSELECT\b|\bINSERT\b|\bUPDATE\b|\bDELETE\b' \
+  -e '\bquery(Raw)?\s*\(' \
+  -e '\bexecute\s*\(' \
+  -e '\bprepare\s*\('
+
+run "File & Path Handling (review traversal/allowlists)" \
+  -e '\bopen\s*\(' \
+  -e '\bos\.path\.join\b|\bpath\.join\b|\bfilepath\.Join\b' \
+  -e '\bread(File|FileSync)\s*\(' \
+  -e '\bwrite(File|FileSync)\s*\(' \
+  -e '\bcreate(Read|Write)Stream\s*\(' \
+  -e '\bSendFile\b|\bsendFile\s*\('
+
+run "AuthN/AuthZ Signals (review enforcement points)" \
+  -e '\bauthori[sz]e\b' \
+  -e '\bpermission(s)?\b' \
+  -e '\brole(s)?\b' \
+  -e '\bisAdmin\b|\badminOnly\b' \
+  -e '\bRBAC\b|\bABAC\b'
+
+run "Secrets (high false positives; prioritize obvious tokens/keys)" \
+  -e 'AKIA[0-9A-Z]{16}' \
+  -e 'ASIA[0-9A-Z]{16}' \
+  -e '-----BEGIN (RSA|EC|OPENSSH) PRIVATE KEY-----' \
+  -e 'xox[baprs]-[0-9A-Za-z-]+' \
+  -e 'ghp_[0-9A-Za-z]{30,}' \
+  -e 'AIza[0-9A-Za-z\-_]{35}' \
+  -e '\b(api[_-]?key|secret|token|passwd|password)\b\s*[:=]\s*["'\''][^"'\'']{8,}["'\'']'

package/skills/audit/scripts/stamp_file_state.py

@@ -0,0 +1,349 @@
+#!/usr/bin/env python3
+"""
+Walk the target repository, hash every source file, and write
+archon/file-state.json — a per-file lattice that records which audit IDs
+have touched which file. Run this as a side-effect of the final phase of
+any audit (balanced Phase B8, deep Phase D13) so the next audit can compute
+an incremental scope (changed/new/deleted files) against the prior state.
+
+The state file is additive across runs: a re-run merges the new audit_id
+into each file's `last_audits[]` rather than overwriting.
+
+Usage:
+    stamp_file_state.py [--target <path>] [--archon-dir <path>] [--audit-id <id>] [--phases <n,n,...>]
+
+Defaults:
+    --target       cwd
+    --archon-dir   <target>/archon
+    --audit-id     read from <archon-dir>/audit-state.json's last entry
+    --phases       all integer keys from the last audit's `phases` map
+
+Excludes:
+    Standard noise (.git/, node_modules/, vendor/, __pycache__/, dist/,
+    build/, .venv/, target/, .archon-merge-staging-*/) and the archon/
+    directory itself. Only files smaller than DEFAULT_MAX_BYTES (~512KB)
+    are hashed; larger files get a `large_file: true` marker without a
+    hash so the next audit still sees that they exist.
+
+Exit codes:
+    0  success
+    1  no audit_id available (no prior audit-state.json and none provided)
+    2  usage error / target missing
+    3  I/O failure during walk or write
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+DEFAULT_MAX_BYTES = 512 * 1024  # 512 KB cap per file before we skip hashing
+
+EXCLUDED_DIR_NAMES = {
+    ".git",
+    ".hg",
+    ".svn",
+    "node_modules",
+    "vendor",
+    "__pycache__",
+    ".venv",
+    "venv",
+    ".tox",
+    "dist",
+    "build",
+    "target",
+    ".next",
+    ".nuxt",
+    ".cache",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".ruff_cache",
+    ".gradle",
+    ".idea",
+    ".vscode",
+    "archon",
+}
+
+EXCLUDED_DIR_PREFIXES = (".archon-merge-staging-", "bak-archon-")
+
+# Hashed only — extensions are intentionally broad. If a file has no
+# extension we still hash it as long as it's not obviously a binary blob
+# (we sniff the first chunk for null bytes).
+TEXT_HINT_EXTENSIONS = {
+    # source
+    ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+    ".py", ".rb", ".go", ".rs", ".java", ".kt", ".scala",
+    ".c", ".cc", ".cpp", ".h", ".hpp", ".m", ".mm",
+    ".cs", ".fs", ".vb", ".swift", ".dart",
+    ".php", ".pl", ".pm", ".lua", ".r", ".jl", ".ex", ".exs",
+    ".erl", ".hrl", ".clj", ".cljs", ".elm", ".purs",
+    ".sh", ".bash", ".zsh", ".fish", ".ps1", ".bat", ".cmd",
+    ".sql", ".graphql", ".gql", ".proto", ".thrift", ".avsc",
+    # config / infra
+    ".json", ".yaml", ".yml", ".toml", ".ini", ".env", ".conf",
+    ".tf", ".hcl", ".tfvars", ".dockerfile",
+    # docs
+    ".md", ".mdx", ".rst", ".txt",
+}
+
+
+def is_excluded_dir(name: str) -> bool:
+    if name in EXCLUDED_DIR_NAMES:
+        return True
+    return any(name.startswith(p) for p in EXCLUDED_DIR_PREFIXES)
+
+
+def looks_like_text(path: Path, sniff_bytes: int = 4096) -> bool:
+    """Cheap binary sniff. We hash anything that has a text-y extension or
+    that doesn't trip the null-byte heuristic in its first chunk."""
+    if path.suffix.lower() in TEXT_HINT_EXTENSIONS:
+        return True
+    # No extension or unfamiliar extension — sniff content.
+    try:
+        with path.open("rb") as f:
+            chunk = f.read(sniff_bytes)
+    except OSError:
+        return False
+    if not chunk:
+        return True  # empty file is fine
+    return b"\x00" not in chunk
+
+
+def hash_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for buf in iter(lambda: f.read(64 * 1024), b""):
+            h.update(buf)
+    return h.hexdigest()
+
+
+def walk_target(target: Path) -> list[Path]:
+    out: list[Path] = []
+    target = target.resolve()
+    for root, dirs, files in os.walk(target):
+        # Prune in place — modifying `dirs` skips them entirely.
+        dirs[:] = [d for d in dirs if not is_excluded_dir(d)]
+        root_path = Path(root)
+        for name in files:
+            full = root_path / name
+            if not full.is_file():
+                continue
+            try:
+                if full.is_symlink():
+                    continue
+            except OSError:
+                continue
+            out.append(full)
+    return sorted(out)
+
+
+def load_prior(state_path: Path) -> dict:
+    if not state_path.is_file():
+        return {"audits": [], "files": {}}
+    try:
+        return json.loads(state_path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return {"audits": [], "files": {}}
+
+
+def detect_audit_id(archon_dir: Path) -> Optional[tuple[str, list[int]]]:
+    """Pull the most recent audit's id + phase keys from audit-state.json.
+    Returns (audit_id, phase_numbers) or None if the file is unreadable.
+    """
+    audit_state = archon_dir / "audit-state.json"
+    if not audit_state.is_file():
+        return None
+    try:
+        data = json.loads(audit_state.read_text())
+    except (OSError, json.JSONDecodeError):
+        return None
+    audits = data.get("audits") or []
+    if not audits:
+        return None
+    last = audits[-1]
+    audit_id = (last.get("audit_id") or "").strip()
+    if not audit_id:
+        return None
+    phase_map = last.get("phases") or {}
+    phases: list[int] = []
+    for key in phase_map.keys():
+        try:
+            phases.append(int(key))
+        except (TypeError, ValueError):
+            continue
+    phases.sort()
+    return audit_id, phases
+
+
+def stamp(
+    target: Path,
+    archon_dir: Path,
+    audit_id: str,
+    phases: list[int],
+    max_bytes: int = DEFAULT_MAX_BYTES,
+) -> dict:
+    state_path = archon_dir / "file-state.json"
+    state = load_prior(state_path)
+    files: dict = state.get("files") or {}
+    audits_seen: list = state.get("audits") or []
+
+    target = target.resolve()
+    paths = walk_target(target)
+    seen_rel: set[str] = set()
+
+    for full in paths:
+        try:
+            rel = str(full.relative_to(target))
+        except ValueError:
+            continue
+        seen_rel.add(rel)
+
+        try:
+            stat = full.stat()
+        except OSError:
+            continue
+
+        prior = files.get(rel) or {}
+        large = stat.st_size > max_bytes
+        text = looks_like_text(full) if not large else False
+
+        record: dict = {
+            "size": stat.st_size,
+            "last_audit_id": audit_id,
+        }
+        prior_audits = list(prior.get("last_audits") or [])
+        if audit_id not in prior_audits:
+            prior_audits.append(audit_id)
+        record["last_audits"] = prior_audits[-10:]  # cap history per file
+
+        prior_phases = list(prior.get("last_phases") or [])
+        merged_phases = sorted(set(prior_phases) | set(phases))
+        record["last_phases"] = merged_phases
+
+        if large:
+            record["large_file"] = True
+            # Preserve any prior hash so a follow-up tool can still detect
+            # truncation back below the cap.
+            if "hash" in prior:
+                record["hash"] = prior["hash"]
+        elif not text:
+            record["binary"] = True
+            if "hash" in prior:
+                record["hash"] = prior["hash"]
+        else:
+            try:
+                record["hash"] = hash_file(full)
+            except OSError as exc:
+                record["hash_error"] = str(exc)
+
+        files[rel] = record
+
+    # Mark deleted files (present in prior state, missing from this walk).
+    for rel, prior in list(files.items()):
+        if rel in seen_rel:
+            continue
+        prior["deleted_in_audit"] = audit_id
+        files[rel] = prior
+
+    if audit_id not in audits_seen:
+        audits_seen.append(audit_id)
+
+    state.update(
+        {
+            "schema_version": 1,
+            "audit_id": audit_id,
+            "audits": audits_seen[-25:],
+            "stamped_at": datetime.now(timezone.utc).isoformat(),
+            "target": str(target),
+            "files": files,
+        }
+    )
+
+    state_path.parent.mkdir(parents=True, exist_ok=True)
+    state_path.write_text(json.dumps(state, indent=2, sort_keys=True) + "\n")
+
+    counts = {
+        "tracked": len(files),
+        "with_hash": sum(1 for r in files.values() if r.get("hash")),
+        "large_skipped": sum(1 for r in files.values() if r.get("large_file")),
+        "binary_skipped": sum(1 for r in files.values() if r.get("binary")),
+        "deleted": sum(1 for r in files.values() if r.get("deleted_in_audit")),
+    }
+    return counts
+
+
+def parse_phases_arg(raw: str) -> list[int]:
+    if not raw:
+        return []
+    out: list[int] = []
+    for piece in raw.split(","):
+        piece = piece.strip()
+        if not piece:
+            continue
+        try:
+            out.append(int(piece))
+        except ValueError:
+            print(f"warning: ignoring non-integer phase {piece!r}", file=sys.stderr)
+    return sorted(set(out))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--target", default=".", help="Target repository path (default: cwd)")
+    parser.add_argument("--archon-dir", default=None, help="Archon data dir (default: <target>/archon)")
+    parser.add_argument("--audit-id", default=None, help="Override the audit id to stamp (default: read from audit-state.json)")
+    parser.add_argument("--phases", default=None, help="Comma-separated phase numbers to mark on each file (default: all phases from current audit)")
+    parser.add_argument("--max-bytes", type=int, default=DEFAULT_MAX_BYTES, help="Skip hashing for files larger than this many bytes")
+    args = parser.parse_args()
+
+    target = Path(args.target).resolve()
+    if not target.is_dir():
+        print(f"error: target is not a directory: {target}", file=sys.stderr)
+        sys.exit(2)
+
+    archon_dir = Path(args.archon_dir) if args.archon_dir else target / "archon"
+    archon_dir.mkdir(parents=True, exist_ok=True)
+
+    audit_id = args.audit_id
+    phases: list[int] = parse_phases_arg(args.phases or "")
+
+    if not audit_id or not phases:
+        detected = detect_audit_id(archon_dir)
+        if detected is None and not audit_id:
+            print(
+                "error: no audit_id provided and audit-state.json is unreadable",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        if detected is not None:
+            det_id, det_phases = detected
+            if not audit_id:
+                audit_id = det_id
+            if not phases:
+                phases = det_phases
+
+    try:
+        counts = stamp(target, archon_dir, audit_id, phases, max_bytes=args.max_bytes)
+    except OSError as exc:
+        print(f"error: I/O failure during stamp: {exc}", file=sys.stderr)
+        sys.exit(3)
+
+    state_path = archon_dir / "file-state.json"
+    print(
+        f"file-state stamped at {state_path}: "
+        f"{counts['tracked']} tracked "
+        f"({counts['with_hash']} hashed, "
+        f"{counts['large_skipped']} large-skipped, "
+        f"{counts['binary_skipped']} binary-skipped, "
+        f"{counts['deleted']} marked deleted)"
+    )
+
+
+if __name__ == "__main__":
+    main()

package/skills/code-reviewer/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: code-reviewer
+description:
+  Use this skill to review code. It supports both local changes (staged or working tree)
+  and remote Pull Requests (by ID or URL). It focuses on correctness, maintainability,
+  and adherence to project standards.
+---
+
+# Code Reviewer
+
+This skill guides the agent in conducting professional and thorough code reviews for both local development and remote Pull Requests.
+
+## Workflow
+
+### 1. Determine Review Target
+*   **Remote PR**: If the user provides a PR number or URL (e.g., "Review PR #123"), target that remote PR.
+*   **Local Changes**: If no specific PR is mentioned, or if the user asks to "review my changes", target the current local file system states (staged and unstaged changes).
+
+### 2. Preparation
+
+#### For Remote PRs:
+1.  **Checkout**: Use the GitHub CLI to checkout the PR.
+    ```bash
+    gh pr checkout <PR_NUMBER>
+    ```
+2.  **Preflight**: Execute the project's standard verification suite to catch automated failures early.
+    ```bash
+    npm run preflight
+    ```
+3.  **Context**: Read the PR description and any existing comments to understand the goal and history.
+
+#### For Local Changes:
+1.  **Identify Changes**:
+    *   Check status: `git status`
+    *   Read diffs: `git diff` (working tree) and/or `git diff --staged` (staged).
+2.  **Preflight (Optional)**: If the changes are substantial, ask the user if they want to run `npm run preflight` before reviewing.
+
+### 3. In-Depth Analysis
+Analyze the code changes based on the following pillars:
+
+*   **Correctness**: Does the code achieve its stated purpose without bugs or logical errors?
+*   **Maintainability**: Is the code clean, well-structured, and easy to understand and modify in the future? Consider factors like code clarity, modularity, and adherence to established design patterns.
+*   **Readability**: Is the code well-commented (where necessary) and consistently formatted according to our project's coding style guidelines?
+*   **Efficiency**: Are there any obvious performance bottlenecks or resource inefficiencies introduced by the changes?
+*   **Security**: Are there any potential security vulnerabilities or insecure coding practices?
+*   **Edge Cases and Error Handling**: Does the code appropriately handle edge cases and potential errors?
+*   **Testability**: Is the new or modified code adequately covered by tests (even if preflight checks pass)? Suggest additional test cases that would improve coverage or robustness.
+
+### 4. Provide Feedback
+
+#### Structure
+*   **Summary**: A high-level overview of the review.
+*   **Findings**:
+    *   **Critical**: Bugs, security issues, or breaking changes.
+    *   **Improvements**: Suggestions for better code quality or performance.
+    *   **Nitpicks**: Formatting or minor style issues (optional).
+*   **Conclusion**: Clear recommendation (Approved / Request Changes).
+
+#### Tone
+*   Be constructive, professional, and friendly.
+*   Explain *why* a change is requested.
+*   For approvals, acknowledge the specific value of the contribution.
+
+### 5. Cleanup (Remote PRs only)
+*   After the review, ask the user if they want to switch back to the default branch (e.g., `main` or `master`).