codereview-loop 0.13.0__py3-none-any.whl

codereview/tiering.py

@@ -0,0 +1,265 @@
+#!/usr/bin/env python3
+"""Tiered panels and escalation — Epic E2 + E4 of the adopted
+roadmap.
+
+E1's risk scorer describes a change; this module ACTS on the
+description to size the panel that reviews it:
+
+  * band "low"    → a designated pre-screen seat (or seats)
+                    only;
+  * band "medium" → a reduced panel;
+  * band "high"   → the full panel, and evidence is required
+                    (the Epic C rule: required evidence that
+                    is missing BLOCKS the gate). "Missing"
+                    includes the run where the caller supplied
+                    no evidence record at all — the tiering
+                    policy is itself the requirement. A supplied
+                    record whose required item is UNAVAILABLE
+                    (tool not installed) is the other C3 branch
+                    and makes the gate INCONCLUSIVE instead
+                    (P6-11: the two statuses are per-item, and
+                    an absent record is not an item).
+
+E4 is the safety valve on the smaller tiers: if the
+pre-screen / reduced panel returns uncertainty or any
+blocking finding, the run escalates to the full panel WITHIN
+the same run. The triggers are stated in the product's
+existing vocabulary, never a parallel one:
+
+  * "blocking finding" — a stage-1 reviewer report carries a
+    finding whose severity is in the gate's blocking set
+    (the same set core._gate applies, allow_major included);
+  * "reviewer failure" — a stage-1 reviewer job ended in
+    error after its fallbacks: the seat could not answer, so
+    the small panel's answer is incomplete by the run's own
+    degraded vocabulary;
+  * "lens unserved: <lens>" — a lens the full panel tasks has
+    no successful stage-1 report while stage-2 seats remain
+    to serve it: the small panel structurally did not cover
+    the change (the S1/coverage vocabulary).
+
+Escalation never removes anything: stage-1 reports and
+findings stay in the run, and the final verdict is computed
+on the full evidence of the run by the normal gate rules.
+A finding the pre-screen raised is neither withdrawn nor
+discounted because the full panel also served.
+
+Configuration lives in the [risk] table of .codereview.toml
+(policy.py validates it in the B1 style): `tiering = true`
+turns the machinery on (it consumes the band, so [risk]
+`enabled` must be true too — policy load rejects the
+combination otherwise). `prescreen_seats` names the low
+tier's seats (default: the first seat of the composed
+panel); `medium_seats` names the medium tier's seats
+(default: the first tasked seat per lens). A configured name
+that is not on the composed panel is recorded in the run's
+`tiering` section as a missing seat — never silently
+dropped — and if filtering would leave a tier with NO seats
+at all, the run falls back to the full panel with the
+reason recorded: a configuration accident must never produce
+an unreviewed run.
+
+Seat–lens binding (S1) is untouched: under an explicit
+binding, tiering filters the derived task list by seat, so
+a seat serves exactly its bound lens(es) at every tier — a
+reduced panel is a subset of seats with their bound lenses,
+never a re-mapping. Under the legacy seat-order assignment
+there is no binding to violate: the tier's seats form a
+smaller panel and are tasked by the ordinary derivation
+rule (a lone pre-screen seat is called once per lens,
+exactly as a one-seat panel is today).
+
+Deterministic control flow: no model calls in this module.
+The plan and the trigger evaluation are pure functions of
+the risk section, the derived tasks, the resolved config,
+and the stage-1 reports.
+
+With tiering unconfigured — no policy, [risk] disabled, or
+`tiering` absent/false — core.run_review never consults
+this module: no record section, no staged execution, the
+run is byte-identical to the pre-E2 construction, which the
+bench and the registered confirmation runs rely on: they
+never enable it. Verification rounds are out of scope,
+exactly as for E1/E3: run_verification carries no project
+policy today, so there is no tiering surface there either.
+"""
+
+from __future__ import annotations
+
+SCHEMA = "codereview.tiering/1"
+
+# The escalation trigger kinds, in the order they are
+# evaluated and recorded.
+TRIGGER_BLOCKING_FINDING = "blocking finding"
+TRIGGER_REVIEWER_FAILURE = "reviewer failure"
+TRIGGER_LENS_UNSERVED = "lens unserved"
+
+
+def tiering_config(policy):
+    """The resolved tiering config carried by a loaded policy
+    dict, or None when tiering is not enabled (no policy, no
+    [risk] table, scoring disabled, or tiering = false) — the
+    caller then runs exactly as it did before Epic E2.
+
+    Defensive by construction, mirroring risk.risk_config:
+    a hand-built policy dict with missing or mistyped values
+    resolves to the defaults rather than raising mid-run; the
+    validating layer is policy.load_policy (which also
+    rejects tiering = true with enabled = false)."""
+    if not isinstance(policy, dict):
+        return None
+    risk = policy.get("risk") or {}
+    if not isinstance(risk, dict) \
+            or not risk.get("enabled") \
+            or not risk.get("tiering"):
+        return None
+
+    def _seats(key):
+        value = risk.get(key)
+        if not isinstance(value, (list, tuple)):
+            return []
+        return [name for name in value
+                if isinstance(name, str) and name]
+
+    return {
+        "prescreen_seats": _seats("prescreen_seats"),
+        "medium_seats": _seats("medium_seats"),
+    }
+
+
+def plan_stages(band, tasks, config):
+    """Choose the tier's seats — the seat-level plan E4's
+    escalation rule runs under.
+
+    `tasks` is core._reviewer_tasks' output — (seat, fn,
+    lens) triples in derivation order, including any
+    fallback tasks run_review appended for binding-unserved
+    lenses; it fixes the panel's seat order and, for the
+    default medium tier, which seat first serves each lens.
+    `config` is a resolved config from tiering_config. The
+    caller turns the seat choice into stage task lists (a
+    binding-filtered subset of `tasks`, or a fresh
+    derivation for the tier's smaller panel under the
+    legacy assignment — see the module docstring).
+
+    Returns {"stage1_seats": [...], "prescreen_seats":
+    [...], "medium_seats": [...] or None,
+    "missing_seats": [...], "fallback_to_full": str or
+    None}. On a full-panel fallback, stage1_seats is the
+    whole panel and the caller runs no second stage.
+    """
+    config = config or {}
+    panel_seats = []
+    for name, _fn, _lens in tasks:
+        if name not in panel_seats:
+            panel_seats.append(name)
+
+    missing = []
+    fallback_to_full = None
+    prescreen = list(config.get("prescreen_seats") or [])
+    medium = list(config.get("medium_seats") or [])
+    if band == "high":
+        stage1_seats = list(panel_seats)
+    elif band == "medium":
+        if medium:
+            for name in medium:
+                if name not in panel_seats \
+                        and name not in missing:
+                    missing.append(name)
+            stage1_seats = [n for n in panel_seats
+                            if n in set(medium)]
+            if not stage1_seats:
+                fallback_to_full = (
+                    "none of the configured medium_seats "
+                    "is on the composed panel")
+        else:
+            # Default reduced panel: the first tasked seat
+            # per lens, in task order — each lens the full
+            # panel serves is served once.
+            stage1_seats = []
+            seen_lenses = set()
+            for name, _fn, lens in tasks:
+                if lens in seen_lenses:
+                    continue
+                seen_lenses.add(lens)
+                if name not in stage1_seats:
+                    stage1_seats.append(name)
+    else:  # "low" (and any unexpected band: the smallest tier)
+        if prescreen:
+            for name in prescreen:
+                if name not in panel_seats \
+                        and name not in missing:
+                    missing.append(name)
+            stage1_seats = [n for n in panel_seats
+                            if n in set(prescreen)]
+            if not stage1_seats:
+                fallback_to_full = (
+                    "none of the configured prescreen_seats "
+                    "is on the composed panel")
+        else:
+            stage1_seats = panel_seats[:1]
+    if fallback_to_full is not None:
+        stage1_seats = list(panel_seats)
+    return {
+        "stage1_seats": stage1_seats,
+        "prescreen_seats": prescreen,
+        "medium_seats": medium or None,
+        "missing_seats": missing,
+        "fallback_to_full": fallback_to_full,
+    }
+
+
+def escalation_triggers(stage1_reports, stage2_tasks,
+                        blocking_sevs):
+    """E4's escalation evaluation over stage 1's results.
+
+    `stage1_reports` is the slice of the run's
+    reviewer_reports the first stage produced (each a report
+    dict with provider/lens/status/findings); `stage2_tasks`
+    is the plan's stage-2 task list — with nothing left to
+    escalate TO, no trigger can fire. `blocking_sevs` is the
+    gate's blocking severity set for this run (core passes
+    ("blocker",) under allow_major, else BLOCKING_DEFAULT).
+
+    Returns a list of trigger entries {"kind", "detail"} in
+    the fixed order: blocking finding, reviewer failure,
+    lens unserved. Empty ⇒ the small panel's answer stands
+    and stage 2 never runs. Pure: reads report dicts only.
+    """
+    if not stage2_tasks:
+        return []
+    reports = list(stage1_reports or [])
+    triggers = []
+
+    blocking = [f for r in reports
+                for f in (r.get("findings") or [])
+                if f.get("severity") in blocking_sevs]
+    if blocking:
+        triggers.append({
+            "kind": TRIGGER_BLOCKING_FINDING,
+            "detail": f"{len(blocking)} blocking finding(s) "
+                      f"from the reduced panel "
+                      f"({', '.join(sorted({f['severity'] for f in blocking}))})"})
+
+    failed = [r for r in reports if r.get("status") == "error"]
+    if failed:
+        triggers.append({
+            "kind": TRIGGER_REVIEWER_FAILURE,
+            "detail": f"{len(failed)} reduced-panel reviewer "
+                      f"job(s) ended in error "
+                      f"({', '.join(sorted({r.get('provider') or '?' for r in failed}))})"})
+
+    covered = {r.get("lens") for r in reports
+               if r.get("status") == "ok"}
+    stage2_lenses = []
+    for _name, _fn, lens in stage2_tasks:
+        if lens not in stage2_lenses:
+            stage2_lenses.append(lens)
+    for lens in stage2_lenses:
+        if lens not in covered:
+            triggers.append({
+                "kind": TRIGGER_LENS_UNSERVED,
+                "detail": f"lens unserved: {lens} — no "
+                          f"successful reduced-panel review "
+                          f"of that lens"})
+    return triggers

codereview/userconfig.py

@@ -0,0 +1,307 @@
+#!/usr/bin/env python3
+"""codereview user setup — the per-user config the FIRST RUN
+creates (owner directive 2026-11-04: "we don't choose the LLM
+model for them").
+
+The product ships NO default panel. On first open the user runs
+the setup wizard (`codereview setup`), picks their providers,
+points at their own keys, assigns a model per role, and saves
+THAT as their defaults. This module is the storage half:
+
+  path    $CODEREVIEW_CONFIG, else $XDG_CONFIG_HOME/codereview/
+          config.toml, else ~/.config/codereview/config.toml
+  content provider SPECS and role -> spec assignments only.
+          A spec names a key ENVIRONMENT VARIABLE (the custom
+          spec grammar) or a registry preset (whose key env the
+          registry names) — key VALUES never appear here, are
+          never prompted into the file, and are never echoed.
+          The wizard also saves the seat metadata it derived
+          for the panel (P6-06: [seat_meta], seat name ->
+          vendor family) so a saved panel's families are the
+          ones setup computed, not a later re-derivation.
+
+Resolution order at run time (cli): explicit --provider/--role
+flags, then $CODEREVIEW_PROVIDERS, then this config. Nothing
+else. A run with none of those is "not set up" and stops with
+instructions — it never falls back to a built-in panel.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import tomllib
+
+
+def config_path(environ=None):
+    environ = os.environ if environ is None else environ
+    override = environ.get("CODEREVIEW_CONFIG", "").strip()
+    if override:
+        return override
+    xdg = environ.get("XDG_CONFIG_HOME", "").strip()
+    base = xdg or os.path.join(environ.get("HOME", "~"), ".config")
+    return os.path.join(base, "codereview", "config.toml")
+
+
+def load_user_config(environ=None):
+    """-> {"providers": [...], "roles": {role: spec}} or None
+    when no setup exists. A malformed config raises ValueError —
+    a broken setup must be loud, never silently ignored."""
+    path = config_path(environ)
+    if not os.path.exists(path):
+        return None
+    with open(path, "rb") as fh:
+        try:
+            data = tomllib.load(fh)
+        except tomllib.TOMLDecodeError as exc:
+            raise ValueError(
+                f"user config {path} is not valid TOML: {exc}")
+    # Type-validate before iterating (open-refutations
+    # hardening, 9a4415ddafa6): a non-list `providers` was
+    # iterated element-wise (a string silently became one
+    # "provider" per character) and a non-table `roles` raised
+    # an uncaught AttributeError from .items() — both break
+    # this function's documented contract that a malformed
+    # config raises ValueError naming the path.
+    raw_providers = data.get("providers")
+    if raw_providers is None:
+        raw_providers = []
+    if not isinstance(raw_providers, list):
+        raise ValueError(
+            f"user config {path}: 'providers' must be a list "
+            f"of provider specs, got "
+            f"{type(raw_providers).__name__}")
+    raw_roles = data.get("roles")
+    if raw_roles is None:
+        raw_roles = {}
+    if not isinstance(raw_roles, dict):
+        raise ValueError(
+            f"user config {path}: 'roles' must be a table of "
+            f"role = \"spec\" entries, got "
+            f"{type(raw_roles).__name__}")
+    providers = [str(p) for p in raw_providers]
+    roles = {str(k): str(v) for k, v in raw_roles.items()}
+    # Epic K3a: the optional [hosting] table — today one key,
+    # `herdr`, a list of SEAT NAMES whose agent seats run
+    # inside herdr panes when herdr is present (see
+    # herdrhost.py). It is a hosting hint in the saved config
+    # only: never part of the agent: spec grammar, so records
+    # written before hosting existed stay valid. Type-
+    # validated like the rest — a malformed table is a loud
+    # ValueError, never a silently ignored hint.
+    raw_hosting = data.get("hosting")
+    if raw_hosting is None:
+        raw_hosting = {}
+    if not isinstance(raw_hosting, dict):
+        raise ValueError(
+            f"user config {path}: 'hosting' must be a table "
+            f"of hosting hints, got "
+            f"{type(raw_hosting).__name__}")
+    raw_herdr = raw_hosting.get("herdr")
+    if raw_herdr is None:
+        raw_herdr = []
+    if not isinstance(raw_herdr, list):
+        raise ValueError(
+            f"user config {path}: 'hosting.herdr' must be a "
+            f"list of seat names, got "
+            f"{type(raw_herdr).__name__}")
+    hosting = {"herdr": [str(s) for s in raw_herdr]}
+    # Epic L4: the optional [notify] table — one key,
+    # `command`, the argv of the operator's local attention
+    # command (see notify.py). It lives HERE, in the user
+    # setup, by design: notifications are operator preference,
+    # never project contract, so the project policy has no
+    # notify key (policy.load_policy rejects the table).
+    # Type-validated like the rest — a malformed table is a
+    # loud ValueError, never a silently ignored command.
+    raw_notify = data.get("notify")
+    if raw_notify is None:
+        raw_notify = {}
+    if not isinstance(raw_notify, dict):
+        raise ValueError(
+            f"user config {path}: 'notify' must be a table "
+            f"of notification settings, got "
+            f"{type(raw_notify).__name__}")
+    raw_command = raw_notify.get("command")
+    if raw_command is None:
+        raw_command = []
+    if not isinstance(raw_command, list) or not all(
+            isinstance(c, str) for c in raw_command):
+        raise ValueError(
+            f"user config {path}: 'notify.command' must be a "
+            f"list of strings (the notify command's argv), "
+            f"got {raw_command!r}")
+    notify = {"command": [str(c) for c in raw_command]}
+    # P6-06: the optional [seat_meta] table — seat name ->
+    # vendor family, written by the setup wizard from the
+    # metadata it derived for the confirmed panel. The CLI
+    # applies it over the derived baseline (explicit
+    # --seat-meta still wins). Type-validated like the rest.
+    raw_seat_meta = data.get("seat_meta")
+    if raw_seat_meta is None:
+        raw_seat_meta = {}
+    if not isinstance(raw_seat_meta, dict) or not all(
+            isinstance(k, str) and isinstance(v, str)
+            for k, v in raw_seat_meta.items()):
+        raise ValueError(
+            f"user config {path}: 'seat_meta' must be a "
+            f"table of seat name = \"family\" entries, got "
+            f"{raw_seat_meta!r}")
+    seat_meta = {str(k): str(v)
+                 for k, v in raw_seat_meta.items()}
+    return {"providers": providers, "roles": roles,
+            "hosting": hosting, "notify": notify,
+            "seat_meta": seat_meta, "path": path}
+
+
+def _toml_str(value):
+    # JSON strings are valid TOML basic strings for the content
+    # specs contain (URLs, names, commands without control chars).
+    return json.dumps(str(value), ensure_ascii=False)
+
+
+def _toml_key(name):
+    # Bare TOML keys are [A-Za-z0-9_-]+; anything else is
+    # written as a quoted key.
+    if re.fullmatch(r"[A-Za-z0-9_-]+", str(name)):
+        return str(name)
+    return _toml_str(name)
+
+
+def save_user_config(providers, roles, environ=None,
+                     hosting=None, notify=None, seat_meta=None):
+    """Write the setup file (specs only — never a key value) and
+    return its path. `hosting` ({"herdr": [seat names]}) adds
+    the [hosting] table; `notify` ({"command": [argv...]})
+    adds the [notify] table (Epic L4); `seat_meta`
+    ({seat name: family}) adds the [seat_meta] table (P6-06);
+    the defaults write exactly the bytes earlier versions
+    wrote, so an unchanged setup stays byte-identical."""
+    path = config_path(environ)
+    os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+    lines = [
+        "# CodeReview user setup — created by `codereview setup`.",
+        "# Provider specs and role assignments only: keys live in",
+        "# the environment variables the specs name, never here.",
+        "providers = [" + ", ".join(
+            _toml_str(p) for p in providers) + "]",
+        "",
+        "[roles]",
+    ]
+    for role in sorted(roles):
+        lines.append(f"{role} = {_toml_str(roles[role])}")
+    herdr_seats = list((hosting or {}).get("herdr") or [])
+    if herdr_seats:
+        lines += [
+            "",
+            "[hosting]",
+            "# Agent seats listed here run inside herdr panes "
+            "when herdr",
+            "# is present (Epic K3a); without herdr they run "
+            "headless.",
+            "herdr = [" + ", ".join(
+                _toml_str(s) for s in herdr_seats) + "]",
+        ]
+    notify_command = list((notify or {}).get("command") or [])
+    if notify_command:
+        lines += [
+            "",
+            "[notify]",
+            "# Attention notifications (Epic L4): this local "
+            "command is",
+            "# run with the event name and a one-line summary "
+            "appended",
+            "# when a seat blocks or the gate reaches a "
+            "verdict.",
+            "command = [" + ", ".join(
+                _toml_str(c) for c in notify_command) + "]",
+        ]
+    seat_meta = dict(seat_meta or {})
+    if seat_meta:
+        lines += [
+            "",
+            "[seat_meta]",
+            "# Seat metadata the setup wizard derived for "
+            "this panel",
+            "# (P6-06): each seat's vendor family. Runs apply "
+            "it over",
+            "# the derived baseline; --seat-meta overrides it "
+            "per seat.",
+        ]
+        for name in sorted(seat_meta):
+            lines.append(
+                f"{_toml_key(name)} = "
+                f"{_toml_str(seat_meta[name])}")
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write("\n".join(lines) + "\n")
+    return path
+
+
+def env_provider_specs(environ=None):
+    environ = os.environ if environ is None else environ
+    env = (environ.get("CODEREVIEW_PROVIDERS")
+           or environ.get("REVIEWLOOP_PROVIDERS", ""))
+    return [s.strip() for s in env.split(",") if s.strip()]
+
+
+def default_provider_specs(environ=None):
+    """The run's provider specs when the user passed none:
+    environment first, then the saved setup. Empty list means
+    NOT SET UP — the caller stops with instructions rather than
+    inventing a panel."""
+    specs = env_provider_specs(environ)
+    if specs:
+        return specs
+    cfg = load_user_config(environ)
+    if cfg and cfg["providers"]:
+        return list(cfg["providers"])
+    return []
+
+
+def default_role_assignments(environ=None):
+    """Saved role -> spec assignments from the user config
+    ({} when no setup exists). Explicit --role flags override
+    these per role at the CLI seam."""
+    cfg = load_user_config(environ)
+    return dict(cfg["roles"]) if cfg else {}
+
+
+def default_hosting_herdr_seats(environ=None):
+    """Seat names the saved setup marks for herdr pane hosting
+    (Epic K3a; [] when no setup or no [hosting] table)."""
+    cfg = load_user_config(environ)
+    if not cfg:
+        return []
+    return list((cfg.get("hosting") or {}).get("herdr") or [])
+
+
+def default_seat_meta(environ=None):
+    """The saved setup's [seat_meta] table ({seat name:
+    family}; {} when no setup or no table)."""
+    cfg = load_user_config(environ)
+    if not cfg:
+        return {}
+    return dict(cfg.get("seat_meta") or {})
+
+
+def default_notify_command(environ=None):
+    """The saved setup's [notify] command argv (Epic L4; []
+    when no setup or no [notify] table). The ONLY source of a
+    notify command: the project policy cannot set one."""
+    cfg = load_user_config(environ)
+    if not cfg:
+        return []
+    return list((cfg.get("notify") or {}).get("command") or [])
+
+
+NOT_SET_UP = (
+    "codereview is not set up yet: no providers were given and "
+    "no saved setup exists.\n"
+    "  Interactive:  run `codereview setup` and pick your "
+    "providers, keys, and per-role models.\n"
+    "  Scripted:     pass --provider <spec> (repeatable), or set "
+    "$CODEREVIEW_PROVIDERS, or run `codereview setup` once on "
+    "this machine.\n"
+    "CodeReview ships no default panel — the models are yours "
+    "to choose.")