alissa-tools-github-reviewloop 0.1.0__py3-none-any.whl

alissa/tools/github/reviewloop/__init__.py

@@ -0,0 +1,8 @@
+"""reviewloop — a GitHub watcher that drives the alissa-code-review
+adversarial review loop (CR1–CR9) to convergence."""
+
+from .config import Config
+from .loop import Action, Decision, ReviewWatcher
+
+__all__ = ["Config", "ReviewWatcher", "Decision", "Action"]
+__version__ = "0.1.0"

alissa/tools/github/reviewloop/__main__.py

@@ -0,0 +1,181 @@
+"""CLI entry point: alissa-reviewloop (or python -m alissa.tools.github.reviewloop)"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import re
+import sys
+from pathlib import Path
+
+from .config import (
+    HUB_ADD,
+    HUB_SKIP,
+    ON_MISSING_CREATE,
+    ON_MISSING_SKIP,
+    ON_MISSING_SPAWN,
+    Config,
+    load_config_file,
+    resolve_config_path,
+)
+from .ghclient import IdentityMismatch
+from .loop import ReviewWatcher
+from .proc import CommandError
+
+log = logging.getLogger(__name__)
+
+
+def parse_pr_ref(ref: str) -> tuple[str, str, int]:
+    """Parse `owner/repo#123` (or a full PR URL) into its parts."""
+    match = re.search(r"([\w.-]+)/([\w.-]+?)(?:#|/pull/)(\d+)", ref)
+    if not match:
+        raise ValueError(f"expected OWNER/REPO#N or a PR URL, got {ref!r}")
+    return match.group(1), match.group(2), int(match.group(3))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="alissa-reviewloop",
+        description="Watch GitHub for review requests and run the adversarial "
+        "review loop (alissa-code-review CR1-CR9).",
+        epilog="Every setting below can also live in the config file; CLI "
+        "arguments win. workspace_root is CLI-only, so one config can drive "
+        "several daemons over different workspaces.",
+    )
+
+    p.add_argument(
+        "--workspace-root",
+        type=Path,
+        default=None,
+        metavar="PATH",
+        help="the Alissa Code Workspace to watch (default: current directory)",
+    )
+    p.add_argument(
+        "-c",
+        "--config-path",
+        "--config",
+        dest="config_path",
+        type=Path,
+        default=None,
+        metavar="PATH",
+        help="config file; without it, ./reviewloop.config.json then "
+        "<workspace-root>/reviewloop.config.json, else defaults only",
+    )
+
+    mode = p.add_argument_group("mode")
+    mode.add_argument("--once", action="store_true", help="run a single poll pass and exit")
+    mode.add_argument(
+        "--pr",
+        metavar="OWNER/REPO#N",
+        help="evaluate one PR directly, bypassing the search — use this to tell "
+        "'the search did not find it' apart from 'the decision was no'",
+    )
+    mode.add_argument("-v", "--verbose", action="store_true")
+
+    over = p.add_argument_group("config overrides (win over the config file)")
+    over.add_argument(
+        "--repo",
+        dest="repos",
+        action="append",
+        metavar="OWNER/REPO",
+        help="only watch this repo; repeatable. Replaces the config list entirely.",
+    )
+    over.add_argument("--poll-interval", type=int, metavar="SECONDS")
+    over.add_argument("--round-cap", type=int, metavar="N", help="CR9 round cap")
+    over.add_argument("--hub-template", metavar="TEMPLATE")
+    over.add_argument("--agent-profile", metavar="NAME")
+    over.add_argument("--reviewer-login", metavar="LOGIN")
+    over.add_argument("--state-path", type=Path, metavar="PATH")
+    over.add_argument(
+        "--on-missing-review-task",
+        choices=[ON_MISSING_SPAWN, ON_MISSING_CREATE, ON_MISSING_SKIP],
+    )
+    over.add_argument("--on-missing-hub", choices=[HUB_SKIP, HUB_ADD])
+
+    dry = over.add_mutually_exclusive_group()
+    dry.add_argument(
+        "--dry-run",
+        dest="dry_run",
+        action="store_true",
+        default=None,
+        help="decide and log, but never enqueue a session or comment",
+    )
+    dry.add_argument(
+        "--no-dry-run",
+        dest="dry_run",
+        action="store_false",
+        help="act for real even if the config sets dry_run",
+    )
+    return p
+
+
+def overrides_from(args: argparse.Namespace) -> dict:
+    """CLI values, with None meaning 'not specified' so the config file shows
+    through. `repos` becomes a tuple so it matches the config-file form."""
+    return {
+        "repos": tuple(args.repos) if args.repos else None,
+        "poll_interval": args.poll_interval,
+        "round_cap": args.round_cap,
+        "hub_template": args.hub_template,
+        "agent_profile": args.agent_profile,
+        "reviewer_login": args.reviewer_login,
+        "state_path": args.state_path,
+        "on_missing_review_task": args.on_missing_review_task,
+        "on_missing_hub": args.on_missing_hub,
+        "dry_run": args.dry_run,
+    }
+
+
+def resolve_config(args: argparse.Namespace) -> Config:
+    workspace_root = args.workspace_root or Path.cwd()
+    path = resolve_config_path(args.config_path, workspace_root)
+
+    file_data = load_config_file(path) if path else {}
+    log.info("config: %s", path or "none found — defaults + CLI arguments only")
+
+    return Config.build(workspace_root, file_data, overrides_from(args))
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s %(levelname)-7s %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+    try:
+        config = resolve_config(args)
+        log.info("workspace: %s", config.workspace_root)
+
+        watcher = ReviewWatcher(config)
+        for warning in watcher.preflight():
+            log.warning(warning)
+
+        if args.pr:
+            owner, repo, number = parse_pr_ref(args.pr)
+            decision = watcher.evaluate(owner, repo, number)
+            print(f"\n{args.pr} → {decision.action.value}")
+            print(f"  round:  {decision.round}")
+            print(f"  reason: {decision.reason or '—'}")
+        elif args.once:
+            watcher.poll_once()
+        else:
+            watcher.run_forever()
+    except IdentityMismatch as exc:
+        print(f"identity error: {exc}", file=sys.stderr)
+        return 2
+    except (FileNotFoundError, ValueError) as exc:
+        print(f"config error: {exc}", file=sys.stderr)
+        return 2
+    except CommandError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 0
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

alissa/tools/github/reviewloop/alissa.py

@@ -0,0 +1,126 @@
+"""Alissa CLI access: locate the review task (CR2) and enqueue the fresh
+reviewer session (orchestration P1)."""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from .proc import CommandError, run, run_json
+
+log = logging.getLogger(__name__)
+
+# A review task is "open" while it can still receive a verdict.
+OPEN_STATUSES = {"committed", "in_progress", "pending_validation", "todo"}
+
+
+@dataclass(frozen=True)
+class Task:
+    ref: str  # TASK-<seq>
+    title: str
+    status: str
+
+    @property
+    def is_open(self) -> bool:
+        return self.status in OPEN_STATUSES
+
+
+def _title_pattern(owner: str, repo: str, number: int) -> re.Pattern[str]:
+    """CR2 title convention: `Review PR <org>/<repo>#<n> (TASK-<origin>)`."""
+    return re.compile(
+        rf"^Review PR\s+{re.escape(owner)}/{re.escape(repo)}#{number}\b",
+        re.IGNORECASE,
+    )
+
+
+class Alissa:
+    def list_tasks(self) -> list[Task]:
+        data = run_json(["alissa", "task", "list", "--json"], timeout=90) or []
+        tasks = []
+        for row in data:
+            seq = row.get("taskSeq")
+            if seq is None:
+                continue
+            tasks.append(
+                Task(
+                    ref=f"TASK-{seq}",
+                    title=row.get("title", ""),
+                    status=row.get("status", ""),
+                )
+            )
+        return tasks
+
+    def find_review_task(self, owner: str, repo: str, number: int) -> Task | None:
+        """CR2: exactly one review task per PR. Reuse it across rounds (CR7)."""
+        pattern = _title_pattern(owner, repo, number)
+        matches = [t for t in self.list_tasks() if pattern.match(t.title) and t.is_open]
+
+        if not matches:
+            return None
+        if len(matches) > 1:
+            # Several verdicts on one task are fine; several tasks per PR are not.
+            log.warning(
+                "CR2 violation: %d open review tasks for %s/%s#%d (%s) -- using %s",
+                len(matches),
+                owner,
+                repo,
+                number,
+                ", ".join(t.ref for t in matches),
+                matches[0].ref,
+            )
+        return matches[0]
+
+    def enqueue_reviewer(
+        self,
+        *,
+        session: str,
+        directive: str,
+        cwd: Path,
+        agent: str,
+        task_ref: str | None,
+        dry_run: bool = False,
+    ) -> None:
+        argv = [
+            "alissa",
+            "tmux",
+            "queue",
+            "add",
+            session,
+            "--agent",
+            agent,
+            "--cwd",
+            str(cwd),
+        ]
+        if task_ref:
+            argv += ["--task", task_ref]
+        argv.append(directive)
+
+        if dry_run:
+            log.info("[dry-run] would enqueue: %s", " ".join(argv[:-1]) + " <directive>")
+            return
+
+        run(argv, timeout=60)
+
+    def add_repo_to_workspace(
+        self, owner: str, repo: str, workspace_root: Path, *, dry_run: bool = False
+    ) -> None:
+        """Hub-ify a repo into the workspace (bare clone + main/ worktree) and
+        record it in alissa-workspace.yaml. Idempotent per the CLI's contract."""
+        argv = ["alissa", "code", "workspace", "add", f"{owner}/{repo}"]
+        if dry_run:
+            log.info("[dry-run] would run: %s (cwd=%s)", " ".join(argv), workspace_root)
+            return
+
+        log.info("hub-ifying %s/%s into %s", owner, repo, workspace_root)
+        # Cloning a repo can be slow; the poll loop tolerates a long pass.
+        run(argv, timeout=600, cwd=workspace_root)
+
+    def worker_running(self) -> bool:
+        """The queue only drains while `alissa worker` reconciles it."""
+        try:
+            out = run(["alissa", "worker", "status"], timeout=30, check=False)
+        except CommandError:
+            return False
+        return "not running" not in out.lower() and "no worker" not in out.lower()

alissa/tools/github/reviewloop/config.py

@@ -0,0 +1,212 @@
+"""Daemon configuration.
+
+Settings come from three layers, later winning over earlier:
+
+1. the defaults on `Config`
+2. a JSON config file (see `resolve_config_path`)
+3. CLI arguments
+
+`workspace_root` is deliberately **not** a config key — it is a property of the
+running process, not of the settings. That lets one config file drive several
+daemons over different workspaces on the same machine, each pointed with
+`--workspace-root` and narrowed with `--repo`.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping
+
+# What to do when a PR has a pending review request but no matching Alissa
+# review task (CR2 is implementer-side, so a third-party PR may not have one).
+ON_MISSING_SPAWN = "spawn_anyway"  # review anyway, PR URL carries the context
+ON_MISSING_SKIP = "skip"  # ignore the PR until a review task appears
+ON_MISSING_CREATE = "warn_and_spawn"  # spawn, but log loudly
+
+_MISSING_MODES = {ON_MISSING_SPAWN, ON_MISSING_SKIP, ON_MISSING_CREATE}
+
+# What to do when a review arrives for a repo that has no worktree hub yet.
+HUB_SKIP = "skip"
+HUB_ADD = "add"  # `alissa code workspace add <org>/<repo>`
+
+_HUB_MODES = {HUB_SKIP, HUB_ADD}
+
+CONFIG_FILENAME = "reviewloop.config.json"
+
+# Keys accepted in the config file. workspace_root is excluded on purpose.
+CONFIG_KEYS = (
+    "hub_template",
+    "poll_interval",
+    "round_cap",
+    "repos",
+    "agent_profile",
+    "reviewer_login",
+    "state_path",
+    "on_missing_review_task",
+    "on_missing_hub",
+    "dry_run",
+)
+
+MIN_POLL_INTERVAL = 10  # the search API allows 30 req/min
+
+
+def default_state_path(workspace_root: Path) -> Path:
+    return Path(workspace_root) / ".reviewloop" / "state.db"
+
+
+@dataclass(frozen=True)
+class Config:
+    # A property of the process, supplied by --workspace-root (default: cwd).
+    workspace_root: Path
+
+    hub_template: str = "{root}/{repo}/main"
+    poll_interval: int = 60
+    round_cap: int = 3  # CR9 default
+
+    # Empty tuple means "every repo that requests a review from me".
+    repos: tuple[str, ...] = ()
+
+    agent_profile: str = "claude"
+    reviewer_login: str | None = None  # None -> resolve once via `gh api user`
+
+    # None means "derive from the workspace" -- read `state_db` for the
+    # resolved location, never this field.
+    state_path: Path | None = None
+
+    on_missing_review_task: str = ON_MISSING_SPAWN
+    on_missing_hub: str = HUB_SKIP
+    dry_run: bool = False
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self, "workspace_root", Path(self.workspace_root).expanduser().resolve()
+        )
+
+    @property
+    def state_db(self) -> Path:
+        """Where the spawn ledger lives. Defaults inside the workspace so two
+        daemons watching different workspaces never share one."""
+        if self.state_path is None:
+            return default_state_path(self.workspace_root)
+        return Path(self.state_path).expanduser()
+
+    @property
+    def manifest_path(self) -> Path:
+        return self.workspace_root / "alissa-workspace.yaml"
+
+    def hub_for(self, owner: str, repo: str) -> Path:
+        return Path(
+            self.hub_template.format(
+                root=str(self.workspace_root), owner=owner, repo=repo
+            )
+        ).expanduser()
+
+    def watches(self, full_name: str) -> bool:
+        return not self.repos or full_name in self.repos
+
+    @classmethod
+    def build(
+        cls,
+        workspace_root: Path,
+        file_data: Mapping[str, Any] | None = None,
+        overrides: Mapping[str, Any] | None = None,
+    ) -> "Config":
+        """Merge the layers and validate. `overrides` entries that are None mean
+        "not specified on the CLI" and fall through to the file / defaults."""
+        raw: dict[str, Any] = dict(file_data or {})
+
+        if "workspace_root" in raw:
+            raise ValueError(
+                "workspace_root is not a config key — it is a property of the "
+                "running process. Pass --workspace-root (or run the daemon from "
+                "the workspace), and remove it from the config file."
+            )
+
+        # Allow "_"-prefixed keys as inline comments, since JSON has none.
+        unknown = {k for k in set(raw) - set(CONFIG_KEYS) if not k.startswith("_")}
+        if unknown:
+            raise ValueError(
+                f"unknown config key(s): {', '.join(sorted(unknown))}. "
+                f"Valid keys: {', '.join(CONFIG_KEYS)}"
+            )
+
+        for key, value in (overrides or {}).items():
+            if value is not None:
+                raw[key] = value
+
+        mode = raw.get("on_missing_review_task", ON_MISSING_SPAWN)
+        if mode not in _MISSING_MODES:
+            raise ValueError(
+                f"on_missing_review_task must be one of {sorted(_MISSING_MODES)}, got {mode!r}"
+            )
+
+        hub_mode = raw.get("on_missing_hub", HUB_SKIP)
+        if hub_mode not in _HUB_MODES:
+            raise ValueError(
+                f"on_missing_hub must be one of {sorted(_HUB_MODES)}, got {hub_mode!r}"
+            )
+
+        repos = tuple(raw.get("repos", ()))
+        if hub_mode == HUB_ADD and not repos:
+            # Anyone who can request a review could otherwise cause an arbitrary
+            # repo to be cloned onto this machine and opened as an agent's cwd.
+            raise ValueError(
+                "on_missing_hub='add' requires a non-empty repos allowlist "
+                "(config `repos`, or one or more --repo flags) — auto-cloning "
+                "whatever repo requests a review is unbounded"
+            )
+
+        cap = int(raw.get("round_cap", 3))
+        if cap < 1:
+            raise ValueError(f"round_cap must be >= 1, got {cap}")
+
+        interval = int(raw.get("poll_interval", 60))
+        if interval < MIN_POLL_INTERVAL:
+            raise ValueError(
+                f"poll_interval must be >= {MIN_POLL_INTERVAL} seconds, got {interval}"
+            )
+
+        state_path = raw.get("state_path")
+        return cls(
+            workspace_root=Path(workspace_root),
+            hub_template=raw.get("hub_template", cls.hub_template),
+            poll_interval=interval,
+            round_cap=cap,
+            repos=repos,
+            agent_profile=raw.get("agent_profile", "claude"),
+            reviewer_login=raw.get("reviewer_login"),
+            state_path=Path(state_path).expanduser() if state_path else None,
+            on_missing_review_task=mode,
+            on_missing_hub=hub_mode,
+            dry_run=bool(raw.get("dry_run", False)),
+        )
+
+
+def load_config_file(path: Path) -> dict[str, Any]:
+    data = json.loads(Path(path).expanduser().read_text())
+    if not isinstance(data, dict):
+        raise ValueError(f"{path}: expected a JSON object, got {type(data).__name__}")
+    return data
+
+
+def resolve_config_path(
+    explicit: Path | None, workspace_root: Path, cwd: Path | None = None
+) -> Path | None:
+    """Find the config file: explicit path, then cwd, then the workspace root.
+
+    Returns None when no config file exists — CLI arguments and defaults alone
+    are a valid way to run. An explicit path that does not exist is an error.
+    """
+    if explicit is not None:
+        path = Path(explicit).expanduser()
+        if not path.is_file():
+            raise FileNotFoundError(f"config file not found: {path}")
+        return path
+
+    cwd = Path.cwd() if cwd is None else Path(cwd)
+    for candidate in (cwd / CONFIG_FILENAME, Path(workspace_root) / CONFIG_FILENAME):
+        if candidate.is_file():
+            return candidate
+    return None

alissa/tools/github/reviewloop/ghclient.py

@@ -0,0 +1,184 @@
+"""GitHub access via `gh api`.
+
+Note: this targets gh 2.4.0, which predates `gh search`. Every query goes
+through `gh api` against the REST v3 endpoints instead.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+from .proc import CommandError, run, run_json
+
+log = logging.getLogger(__name__)
+
+# States that count as "I have reviewed this". PENDING is a draft review that
+# was never submitted, so it does not close a round.
+SUBMITTED_STATES = {"APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED"}
+
+
+@dataclass(frozen=True)
+class PullRequest:
+    owner: str
+    repo: str
+    number: int
+    title: str
+    author: str
+    head_sha: str
+    draft: bool
+    url: str
+
+    @property
+    def full_name(self) -> str:
+        return f"{self.owner}/{self.repo}"
+
+    @property
+    def slug(self) -> str:
+        return f"{self.owner}/{self.repo}#{self.number}"
+
+
+@dataclass(frozen=True)
+class Review:
+    author: str
+    state: str
+    commit_id: str
+    submitted_at: str
+    url: str
+
+
+class RateLimited(RuntimeError):
+    pass
+
+
+class IdentityMismatch(RuntimeError):
+    """Configured reviewer identity disagrees with the gh token."""
+
+
+class GitHub:
+    def __init__(self, login: str | None = None):
+        self._login = login
+
+    def token_login(self) -> str:
+        """Who the gh token actually belongs to. `gh api --jq` prints scalars
+        raw (unquoted), so this is deliberately not parsed as JSON."""
+        return run(["gh", "api", "user", "--jq", ".login"]).strip()
+
+    @property
+    def login(self) -> str:
+        if self._login is None:
+            self._login = self.token_login()
+        return self._login
+
+    def verify_identity(self) -> str:
+        """`review-requested:@me` resolves server-side from the gh token, but
+        round counting filters reviews by `self.login`. If a configured
+        reviewer_login disagrees with the token, the daemon would search one
+        account's queue and count another's reviews — every round would look
+        like round 1 and respawn forever. Fail loudly instead."""
+        actual = self.token_login()
+        if self._login is not None and self._login != actual:
+            raise IdentityMismatch(
+                f"configured reviewer_login={self._login!r} but the gh token "
+                f"belongs to {actual!r}. `@me` follows the token, so round "
+                f"counting would break. Fix reviewer_login (or set it to null "
+                f"to auto-detect), or re-authenticate gh."
+            )
+        self._login = actual
+        return actual
+
+    def _api(self, *args: str, timeout: int = 60):
+        try:
+            return run_json(["gh", "api", *args], timeout=timeout)
+        except CommandError as exc:
+            blob = exc.stderr.lower()
+            if "rate limit" in blob or "403" in blob:
+                raise RateLimited(exc.stderr.strip()[:300]) from exc
+            raise
+
+    def review_requests(self, repos: tuple[str, ...] = ()) -> list[tuple[str, str, int]]:
+        """PRs with a review pending from me.
+
+        `draft:false` enforces CR1 -- draft PRs are never reviewed. GitHub
+        clears the request once a review is submitted and re-adds it when the
+        implementer re-requests, so this doubles as the CR9 round edge-trigger.
+        """
+        query = "is:open is:pr draft:false review-requested:@me"
+        for full_name in repos:
+            query += f" repo:{full_name}"
+
+        payload = self._api(
+            "-X",
+            "GET",
+            "search/issues",
+            "-f",
+            f"q={query}",
+            "-f",
+            "per_page=100",
+        )
+        items = (payload or {}).get("items", [])
+
+        out: list[tuple[str, str, int]] = []
+        for item in items:
+            # repository_url looks like https://api.github.com/repos/<owner>/<repo>
+            parts = item.get("repository_url", "").rstrip("/").split("/")
+            if len(parts) < 2:
+                log.warning("could not parse repo from %s", item.get("repository_url"))
+                continue
+            out.append((parts[-2], parts[-1], int(item["number"])))
+        return out
+
+    def pull_request(self, owner: str, repo: str, number: int) -> PullRequest:
+        data = self._api(f"repos/{owner}/{repo}/pulls/{number}")
+        return PullRequest(
+            owner=owner,
+            repo=repo,
+            number=number,
+            title=data.get("title", ""),
+            author=(data.get("user") or {}).get("login", ""),
+            head_sha=(data.get("head") or {}).get("sha", ""),
+            draft=bool(data.get("draft")),
+            url=data.get("html_url", ""),
+        )
+
+    def reviews(self, owner: str, repo: str, number: int) -> list[Review]:
+        data = (
+            self._api(
+                "-X",
+                "GET",
+                f"repos/{owner}/{repo}/pulls/{number}/reviews",
+                "-f",
+                "per_page=100",
+            )
+            or []
+        )
+        return [
+            Review(
+                author=(r.get("user") or {}).get("login", ""),
+                state=r.get("state", ""),
+                commit_id=r.get("commit_id") or "",
+                submitted_at=r.get("submitted_at") or "",
+                url=r.get("html_url", ""),
+            )
+            for r in data
+        ]
+
+    def my_reviews(self, owner: str, repo: str, number: int) -> list[Review]:
+        """My submitted reviews, oldest first -- one per completed round."""
+        mine = [
+            r
+            for r in self.reviews(owner, repo, number)
+            if r.author == self.login and r.state in SUBMITTED_STATES
+        ]
+        return sorted(mine, key=lambda r: r.submitted_at)
+
+    def comment(self, owner: str, repo: str, number: int, body: str) -> None:
+        run_json(
+            [
+                "gh",
+                "api",
+                f"repos/{owner}/{repo}/issues/{number}/comments",
+                "-f",
+                f"body={body}",
+            ]
+        )

alissa/tools/github/reviewloop/loop.py

@@ -0,0 +1,330 @@
+"""The watcher loop.
+
+One pass = poll GitHub for pending review requests, decide per PR whether a
+fresh reviewer round is owed, and enqueue it. Rounds are derived from GitHub
+(one submitted review per round), not from local bookkeeping.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import time
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+from .alissa import Alissa
+from .config import HUB_ADD, ON_MISSING_SKIP, Config
+from .ghclient import GitHub, PullRequest, RateLimited
+from .proc import CommandError
+from .state import State
+
+log = logging.getLogger(__name__)
+
+# A reviewer session that has not submitted after this long is presumed dead
+# (skill failure mode: "reviewer session stalls"). The round is re-enqueued.
+STALE_ROUND_SECONDS = 90 * 60
+
+ROUND_1_DIRECTIVE = (
+    "You are a PR REVIEWER, not an implementer. {assignment} "
+    "Load the alissa-code-review skill and follow procedures/review-a-pr.md: "
+    "hydrate the task and the PR it names, review per the rubric, post "
+    "severity-tagged comments via gh pr review, record the verdict evidence, "
+    "move the task to pending_validation. "
+    "NEVER push commits, merge, or change PR state. "
+    "Do NOT create further ali-* sessions."
+)
+
+ROUND_K_DIRECTIVE = (
+    "You are a PR REVIEWER, not an implementer — round {round} of a review loop "
+    "(cap {cap}). {assignment} "
+    "Load the alissa-code-review skill and follow procedures/review-a-pr.md "
+    "including its round-k section: verify the triage of every prior finding, "
+    "verify the fixes, sweep the new diff with the full rubric, record a "
+    "round-{round} verdict envelope, move the task to pending_validation. "
+    "NEVER push commits, merge, or change PR state. "
+    "Do NOT create further ali-* sessions."
+)
+
+ESCALATION_COMMENT = (
+    "**Review loop cap-out (CR9)** — {rounds} rounds ran on this PR without "
+    "converging on `approve`. Per the alissa-code-review skill the loop does not "
+    "run past the cap and never silently merges; this needs an operator decision "
+    "(merge with a recorded waiver, direct specific fixes and re-enter with a "
+    "fresh cap, or park it).\n\n"
+    "Last verdict: `{last_state}` at `{sha}`."
+)
+
+
+class Action(str, Enum):
+    SPAWNED = "spawned"
+    IN_FLIGHT = "in-flight"
+    CONVERGED = "converged"
+    CAPPED = "capped"
+    ESCALATED = "escalated"
+    SKIPPED = "skipped"
+
+
+@dataclass(frozen=True)
+class Decision:
+    action: Action
+    reason: str = ""
+    round: int | None = None
+
+
+def session_name(pr: PullRequest, round_: int) -> str:
+    """tmux-safe, unique per (repo, pr, round)."""
+    repo = re.sub(r"[^A-Za-z0-9-]", "-", pr.repo).strip("-").lower()
+    return f"review-{repo}-pr{pr.number}-r{round_}"
+
+
+class ReviewWatcher:
+    def __init__(
+        self,
+        config: Config,
+        github: GitHub | None = None,
+        alissa: Alissa | None = None,
+        state: State | None = None,
+    ):
+        self.config = config
+        self.github = github or GitHub(config.reviewer_login)
+        self.alissa = alissa or Alissa()
+        self.state = state or State(config.state_db)
+
+    # -- per-PR decision ---------------------------------------------------
+
+    def evaluate(self, owner: str, repo: str, number: int) -> Decision:
+        pr = self.github.pull_request(owner, repo, number)
+
+        # CR1: draft PRs are never reviewed. The search already filters these;
+        # this catches a flip back to draft between search and fetch.
+        if pr.draft:
+            return Decision(Action.SKIPPED, "PR is a draft (CR1)")
+
+        if pr.author == self.github.login:
+            # GitHub rejects a self review-request, so this should be
+            # unreachable -- but a shared bot identity would land here.
+            return Decision(
+                Action.SKIPPED,
+                f"PR author is the reviewer identity ({pr.author}); "
+                "GitHub forbids self-review",
+            )
+
+        my_reviews = self.github.my_reviews(owner, repo, number)
+        completed = len(my_reviews)
+
+        if my_reviews and my_reviews[-1].state == "APPROVED":
+            return Decision(Action.CONVERGED, "last verdict is approve", completed)
+
+        # CR9: never queue round cap+1.
+        if completed >= self.config.round_cap:
+            if self.state.escalated(pr.full_name, number, pr.head_sha):
+                return Decision(Action.CAPPED, "already escalated", completed)
+            self._escalate(pr, my_reviews[-1].state if my_reviews else "none", completed)
+            return Decision(Action.ESCALATED, f"{completed} rounds, no approve", completed)
+
+        round_ = completed + 1
+
+        age = self.state.spawn_age(pr.full_name, number, round_)
+        if age is not None and age < STALE_ROUND_SECONDS:
+            return Decision(Action.IN_FLIGHT, f"round {round_} enqueued {int(age)}s ago", round_)
+        if age is not None:
+            log.warning(
+                "%s round %d has been in flight %.0f min with no submitted review "
+                "— re-enqueuing (reviewer session presumed stalled)",
+                pr.slug,
+                round_,
+                age / 60,
+            )
+
+        return self._spawn(pr, round_)
+
+    # -- actions -----------------------------------------------------------
+
+    def _spawn(self, pr: PullRequest, round_: int) -> Decision:
+        task = self.alissa.find_review_task(pr.owner, pr.repo, pr.number)
+
+        if task is None:
+            if self.config.on_missing_review_task == ON_MISSING_SKIP:
+                return Decision(
+                    Action.SKIPPED, "no open Alissa review task (CR2)", round_
+                )
+            log.warning(
+                "%s has no open Alissa review task (CR2) — spawning against the PR "
+                "URL; the reviewer must create or locate one before recording a verdict",
+                pr.slug,
+            )
+            assignment = (
+                f"Review the GitHub PR {pr.url} . There is no Alissa review task for "
+                f"it yet — locate the origin task from the PR and create the downstream "
+                f"review task per CR2 before recording your verdict."
+            )
+        else:
+            assignment = f"You've been assigned Alissa review task {task.ref}."
+
+        template = ROUND_1_DIRECTIVE if round_ == 1 else ROUND_K_DIRECTIVE
+        directive = template.format(
+            assignment=assignment, round=round_, cap=self.config.round_cap
+        )
+
+        hub, problem = self._ensure_hub(pr)
+        if problem is not None:
+            return Decision(Action.SKIPPED, problem, round_)
+
+        name = session_name(pr, round_)
+        self.alissa.enqueue_reviewer(
+            session=name,
+            directive=directive,
+            cwd=hub,
+            agent=self.config.agent_profile,
+            task_ref=task.ref if task else None,
+            dry_run=self.config.dry_run,
+        )
+
+        if not self.config.dry_run:
+            self.state.record_spawn(
+                repo=pr.full_name,
+                number=pr.number,
+                round_=round_,
+                head_sha=pr.head_sha,
+                session=name,
+                task_ref=task.ref if task else None,
+            )
+
+        return Decision(
+            Action.SPAWNED,
+            f"session {name} → {task.ref if task else 'no task'}",
+            round_,
+        )
+
+    def _ensure_hub(self, pr: PullRequest) -> tuple[Path, str | None]:
+        """Resolve the reviewer's cwd, hub-ifying the repo first if configured.
+
+        Returns (hub, problem). `problem` is non-None when the round cannot run.
+        """
+        hub = self.config.hub_for(pr.owner, pr.repo)
+        if hub.is_dir():
+            return hub, None
+
+        if self.config.on_missing_hub != HUB_ADD:
+            return hub, (
+                f"no worktree hub at {hub} — add the repo with "
+                f"`alissa code workspace add {pr.full_name}`, or set "
+                f"on_missing_hub='add' (requires a repos allowlist)"
+            )
+
+        # Guarded twice: config.load() rejects 'add' without an allowlist, and
+        # poll_once() only reaches here for watched repos. Belt and braces --
+        # this path clones code onto the machine and opens it as an agent cwd.
+        if not self.config.watches(pr.full_name):
+            return hub, f"{pr.full_name} is not in the repos allowlist"
+
+        if not self.config.manifest_path.is_file():
+            return hub, (
+                f"{self.config.workspace_root} is not an Alissa Code Workspace "
+                f"(no alissa-workspace.yaml) — run `alissa code workspace init`"
+            )
+
+        try:
+            self.alissa.add_repo_to_workspace(
+                pr.owner,
+                pr.repo,
+                self.config.workspace_root,
+                dry_run=self.config.dry_run,
+            )
+        except CommandError as exc:
+            return hub, f"could not hub-ify {pr.full_name}: {exc}"
+
+        if self.config.dry_run:
+            return hub, None
+        if not hub.is_dir():
+            return hub, (
+                f"`alissa code workspace add {pr.full_name}` reported success but "
+                f"{hub} still does not exist — check hub_template against the "
+                f"manifest's `dir:` override"
+            )
+        return hub, None
+
+    def preflight(self) -> list[str]:
+        """Startup checks. Returns warnings; raises on anything fatal."""
+        warnings: list[str] = []
+
+        # Fatal: a mismatched identity silently breaks round counting.
+        login = self.github.verify_identity()
+        log.info("reviewing as GitHub user %s (from the gh token)", login)
+
+        if not self.config.workspace_root.is_dir():
+            warnings.append(f"workspace_root {self.config.workspace_root} does not exist")
+        elif not self.config.manifest_path.is_file():
+            warnings.append(
+                f"{self.config.workspace_root} has no alissa-workspace.yaml — it is "
+                f"not an Alissa Code Workspace yet (`alissa code workspace init`)"
+            )
+
+        if not self.config.dry_run and not self.alissa.worker_running():
+            warnings.append(
+                "`alissa worker` does not appear to be running — queued reviewer "
+                "sessions will not spawn until it is (`alissa worker start`)"
+            )
+
+        return warnings
+
+    def _escalate(self, pr: PullRequest, last_state: str, rounds: int) -> None:
+        body = ESCALATION_COMMENT.format(
+            rounds=rounds, last_state=last_state.lower(), sha=pr.head_sha[:8]
+        )
+        log.error("CAP-OUT %s after %d rounds — escalating to operator", pr.slug, rounds)
+
+        if self.config.dry_run:
+            log.info("[dry-run] would comment on %s:\n%s", pr.slug, body)
+            return
+
+        try:
+            self.github.comment(pr.owner, pr.repo, pr.number, body)
+        except CommandError as exc:
+            log.error("could not post escalation comment on %s: %s", pr.slug, exc)
+        self.state.record_escalation(pr.full_name, pr.number, pr.head_sha)
+
+    # -- polling -----------------------------------------------------------
+
+    def poll_once(self) -> list[tuple[str, Decision]]:
+        requests = self.github.review_requests(self.config.repos)
+        log.info("%d PR(s) with a review pending from %s", len(requests), self.github.login)
+
+        results = []
+        for owner, repo, number in requests:
+            slug = f"{owner}/{repo}#{number}"
+            if not self.config.watches(f"{owner}/{repo}"):
+                continue
+            try:
+                decision = self.evaluate(owner, repo, number)
+            except RateLimited:
+                raise
+            except CommandError as exc:
+                log.error("%s: %s", slug, exc)
+                decision = Decision(Action.SKIPPED, str(exc))
+
+            level = logging.INFO if decision.action != Action.SKIPPED else logging.DEBUG
+            log.log(level, "%s → %s (%s)", slug, decision.action.value, decision.reason)
+            results.append((slug, decision))
+        return results
+
+    def run_forever(self) -> None:
+        # preflight() is the caller's responsibility -- the CLI runs it once for
+        # every mode, so calling it here too would double every check.
+        backoff = self.config.poll_interval
+        while True:
+            try:
+                self.poll_once()
+                backoff = self.config.poll_interval
+            except RateLimited as exc:
+                backoff = min(backoff * 2, 900)
+                log.warning("rate limited (%s) — backing off %ds", exc, backoff)
+            except CommandError as exc:
+                backoff = min(backoff * 2, 900)
+                log.error("poll failed: %s — retrying in %ds", exc, backoff)
+            except KeyboardInterrupt:
+                log.info("stopping")
+                return
+            time.sleep(backoff)

alissa/tools/github/reviewloop/proc.py

@@ -0,0 +1,56 @@
+"""Subprocess helpers. Everything shells out to `gh` and `alissa` so both keep
+their own auth handling; we never touch tokens ourselves."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import subprocess
+from typing import Sequence
+
+log = logging.getLogger(__name__)
+
+
+class CommandError(RuntimeError):
+    def __init__(self, argv: Sequence[str], returncode: int, stderr: str):
+        self.argv = list(argv)
+        self.returncode = returncode
+        self.stderr = stderr
+        super().__init__(f"{argv[0]} exited {returncode}: {stderr.strip()[:400]}")
+
+
+def run(
+    argv: Sequence[str],
+    *,
+    timeout: int = 60,
+    check: bool = True,
+    cwd: "str | os.PathLike[str] | None" = None,
+) -> str:
+    """Run a command, return stdout. Never uses shell=True."""
+    log.debug("exec: %s", " ".join(argv))
+    try:
+        proc = subprocess.run(
+            list(argv),
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            cwd=str(cwd) if cwd is not None else None,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise CommandError(argv, -1, f"timed out after {timeout}s") from exc
+
+    if check and proc.returncode != 0:
+        raise CommandError(argv, proc.returncode, proc.stderr)
+    return proc.stdout
+
+
+def run_json(argv: Sequence[str], *, timeout: int = 60):
+    """Run a command whose stdout is JSON."""
+    out = run(argv, timeout=timeout).strip()
+    if not out:
+        return None
+    try:
+        return json.loads(out)
+    except json.JSONDecodeError as exc:
+        raise CommandError(argv, 0, f"expected JSON, got: {out[:300]}") from exc

alissa/tools/github/reviewloop/state.py

@@ -0,0 +1,97 @@
+"""Local spawn ledger.
+
+Deliberately thin: GitHub is the source of truth for how many rounds have run
+(one submitted review per round). This table exists only to stop the daemon
+double-spawning a reviewer while a round is still in flight, and to remember
+that a cap-out was already escalated.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import time
+from pathlib import Path
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS spawns (
+    repo       TEXT    NOT NULL,
+    number     INTEGER NOT NULL,
+    round      INTEGER NOT NULL,
+    head_sha   TEXT    NOT NULL,
+    session    TEXT    NOT NULL,
+    task_ref   TEXT,
+    spawned_at INTEGER NOT NULL,
+    PRIMARY KEY (repo, number, round)
+);
+
+CREATE TABLE IF NOT EXISTS escalations (
+    repo         TEXT    NOT NULL,
+    number       INTEGER NOT NULL,
+    head_sha     TEXT    NOT NULL,
+    escalated_at INTEGER NOT NULL,
+    PRIMARY KEY (repo, number, head_sha)
+);
+"""
+
+
+class State:
+    def __init__(self, path: Path):
+        path = Path(path).expanduser()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self._db = sqlite3.connect(str(path))
+        self._db.row_factory = sqlite3.Row
+        self._db.executescript(SCHEMA)
+        self._db.commit()
+
+    def close(self) -> None:
+        self._db.close()
+
+    def __enter__(self) -> "State":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    def get_spawn(self, repo: str, number: int, round_: int) -> sqlite3.Row | None:
+        return self._db.execute(
+            "SELECT * FROM spawns WHERE repo=? AND number=? AND round=?",
+            (repo, number, round_),
+        ).fetchone()
+
+    def spawn_age(self, repo: str, number: int, round_: int) -> float | None:
+        """Seconds since round `round_` was enqueued, or None if never spawned."""
+        row = self.get_spawn(repo, number, round_)
+        return None if row is None else time.time() - row["spawned_at"]
+
+    def record_spawn(
+        self,
+        *,
+        repo: str,
+        number: int,
+        round_: int,
+        head_sha: str,
+        session: str,
+        task_ref: str | None,
+    ) -> None:
+        self._db.execute(
+            "INSERT OR REPLACE INTO spawns "
+            "(repo, number, round, head_sha, session, task_ref, spawned_at) "
+            "VALUES (?,?,?,?,?,?,?)",
+            (repo, number, round_, head_sha, session, task_ref, int(time.time())),
+        )
+        self._db.commit()
+
+    def escalated(self, repo: str, number: int, head_sha: str) -> bool:
+        row = self._db.execute(
+            "SELECT 1 FROM escalations WHERE repo=? AND number=? AND head_sha=?",
+            (repo, number, head_sha),
+        ).fetchone()
+        return row is not None
+
+    def record_escalation(self, repo: str, number: int, head_sha: str) -> None:
+        self._db.execute(
+            "INSERT OR REPLACE INTO escalations "
+            "(repo, number, head_sha, escalated_at) VALUES (?,?,?,?)",
+            (repo, number, head_sha, int(time.time())),
+        )
+        self._db.commit()

alissa/tools/github/reviewloop/version

@@ -0,0 +1 @@
+0.1.0

alissa/tools/github/reviewloop/version.py

@@ -0,0 +1,46 @@
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Version:
+    name: str
+    value: str
+
+    def components(self, as_int: bool = False) -> list:
+        return [int(val) if as_int else val for val in self.value.split(".")]
+
+    @property
+    def major(self) -> int:
+        component, *_ = self.components(as_int=True)
+        return component
+
+    @property
+    def minor(self) -> int:
+        _, component, *_ = self.components(as_int=True)
+        return component
+
+    @property
+    def patch(self) -> int:
+        *_, component = self.components(as_int=True)
+        return component
+
+    @classmethod
+    def from_path(cls, dirpath: str, name: str):
+        for file in os.listdir(dirpath):
+            if file.lower().endswith("version"):
+                filepath = os.path.join(dirpath, file)
+                break
+        else:
+            raise ValueError("Version file not found for package name: " + name)
+
+        with open(filepath, "r") as version_file:
+            version_value = version_file.readline().strip()
+            return cls(name=name, value=version_value)
+
+
+try:
+    version = Version.from_path(name="alissa-tools-github-reviewloop", dirpath=os.path.dirname(__file__))
+except Exception:
+    print("Version file not found for package name: alissa-tools-github-reviewloop, using 0.0.0")
+    version = Version(name="alissa-tools-github-reviewloop", value="0.0.0")

alissa_tools_github_reviewloop-0.1.0.dist-info/METADATA

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: alissa-tools-github-reviewloop
+Version: 0.1.0
+Summary: ALISSA-TOOLS-GITHUB-REVIEWLOOP
+Home-page: https://alissa.app
+Author: Fahera
+Author-email: support@alissa.app
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-python
+Dynamic: summary
+
+# alissa-tools-github-reviewloop
+
+The `alissa.tools.github.reviewloop` module: a GitHub watcher that drives the
+`alissa-code-review` adversarial review loop (CR1–CR9) to convergence.
+
+This distribution ships **only** that module. Everything above it —
+`alissa`, `alissa.tools`, `alissa.tools.github` — is a
+[PEP 420](https://peps.python.org/pep-0420/) namespace package with no
+`__init__.py`, so other distributions in other repositories can contribute
+their own packages under the same namespace:
+
+```
+alissa/                                  ← namespace (no __init__.py)
+└── tools/                               ← namespace
+    ├── github/                          ← namespace
+    │   ├── reviewloop/   __init__.py    ← THIS distribution
+    │   └── issues/       __init__.py    ← could ship from another repo
+    └── slack/                           ← namespace
+        └── notify/       __init__.py    ← could ship from another repo
+```
+
+The rule: a distribution owns a leaf package and declares only that subtree
+(`find_namespace_packages(include=[PACKAGE, f"{PACKAGE}.*"])`). Adding an
+`__init__.py` at any namespace level would claim it for one distribution and
+shadow the others.
+
+## Install
+
+```sh
+pip install -e ./alissa-tools-github-reviewloop
+```
+
+## Console scripts
+
+| Command | Entry point |
+| --- | --- |
+| `alissa-reviewloop` | `alissa.tools.github.reviewloop.__main__:main` |
+
+## Layout
+
+`src/main` holds the package tree, `src/test` mirrors it as `test_*`. The
+distribution version lives in the plain-text `version` file next to the module
+it versions (`src/main/alissa/tools/github/reviewloop/version`), read by both
+`setup.py` and `version.py`.

alissa_tools_github_reviewloop-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+alissa/tools/github/reviewloop/__init__.py,sha256=JVMPodE5m3wNGMcdeTEuoZf4hF1og5-PTeb73WzVn3Q,286
+alissa/tools/github/reviewloop/__main__.py,sha256=7yt99MnIUlLPhZrg9ldXRIJ4GUSdNdPrpKWYLC3bO3g,6024
+alissa/tools/github/reviewloop/alissa.py,sha256=MnnFn9IlbRGEPEBxvqegRh0cYUO6jRmmyY07AOeesuY,3949
+alissa/tools/github/reviewloop/config.py,sha256=JrP_wJhlDh--QCLtcHnPa8YZYY5sxGCE38mOjkxqi4s,7600
+alissa/tools/github/reviewloop/ghclient.py,sha256=bKT2fEGVngVn0SwYI296_S7gCGkxA8wqpoSvn18HlIU,6007
+alissa/tools/github/reviewloop/loop.py,sha256=MNluMOAREnpvuh_OuZC_S7HnLemADtxzFwRIDCjgUrQ,12968
+alissa/tools/github/reviewloop/proc.py,sha256=_dDr3g76WEf2DRyLUz1Dzl4KvLVptJant_UZOrRixNk,1649
+alissa/tools/github/reviewloop/state.py,sha256=wkrf7v6K9dnDgYzVpKTUYDdT7JwovFjqvOM-yV_d5IE,3033
+alissa/tools/github/reviewloop/version,sha256=atlhOkVXmNbZLl9fOQq0uqcFlryGntaxf1zdKyhjXwY,5
+alissa/tools/github/reviewloop/version.py,sha256=m6atW-IvTLm8R2UwtMiXtnXUihPk0EyrtMJwZr1MWCg,1427
+alissa_tools_github_reviewloop-0.1.0.dist-info/METADATA,sha256=kQotlA9NhVcxHJ_2N8CeliFlM-jQbomW8FQn_99Z7xc,2136
+alissa_tools_github_reviewloop-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+alissa_tools_github_reviewloop-0.1.0.dist-info/entry_points.txt,sha256=vynlUoMGQ299ZKbXbZFCdsUqFo7_Wcm5HMZfBHRn5Bk,83
+alissa_tools_github_reviewloop-0.1.0.dist-info/top_level.txt,sha256=DodjDg-l-TWQnlxG-Vuc3G5sB4O7cWGQwe6XrVx3u-A,7
+alissa_tools_github_reviewloop-0.1.0.dist-info/RECORD,,

alissa_tools_github_reviewloop-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

alissa_tools_github_reviewloop-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+alissa-reviewloop = alissa.tools.github.reviewloop.__main__:main

alissa_tools_github_reviewloop-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+alissa