loopagent-gate 0.4.2__py3-none-any.whl

loopgate/gates/render_task_ledger.py

@@ -0,0 +1,312 @@
+#!/usr/bin/env python3
+"""Write a card's history into the repository, where a clone can read it.
+
+The queue lives in a SQLite file on one machine; `artifacts/` and `handoff/` are gitignored because they
+are evidence of a run. The consequence is that "what did we try, and why did it stop" disappears with the
+laptop. This script renders one card to `backlog/<task-id>.md` — spec, the evidence bundle the worker
+owed, how each run ended, and the review trail — so the memory survives `git clone`.
+
+Execution stays where it was: the board still dispatches, the ledger only records.
+
+    python3 -m loopgate.gates.render_task_ledger t_example
+    python3 -m loopgate.gates.render_task_ledger --all-done
+    python3 -m loopgate.gates.render_task_ledger t_example --dry-run
+
+Verdict: TASK_LEDGER_PASS_0001 (exit 0) when every requested card was rendered;
+TASK_LEDGER_STOP_0001 (exit 1) when a card is unknown or the ledger cannot be written.
+"""
+
+from __future__ import annotations
+
+from loopgate.paths import project_root, gate_file
+
+import argparse
+import datetime
+import json
+import os
+import sqlite3
+import sys
+
+ROOT = project_root()
+PASS_MARKER = "TASK_LEDGER_PASS_0001"
+STOP_MARKER = "TASK_LEDGER_STOP_0001"
+KANBAN_DB = os.path.expanduser("~/.hermes/kanban.db")
+OUT_DIR = "backlog"
+
+try:
+    from loopgate.gates import worker_brief  # noqa: E402
+except ImportError:  # pragma: no cover - the ledger must still render without the brief module
+    worker_brief = None
+
+
+def connect(db: str) -> sqlite3.Connection:
+    conn = sqlite3.connect(f"file:{db}?mode=ro", uri=True)
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+def fetch_task(conn: sqlite3.Connection, task_id: str) -> dict | None:
+    row = conn.execute("select * from tasks where id = ?", (task_id,)).fetchone()
+    return dict(row) if row else None
+
+
+def fetch_runs(conn: sqlite3.Connection, task_id: str) -> list[dict]:
+    rows = conn.execute("select * from task_runs where task_id = ? order by id", (task_id,)).fetchall()
+    return [dict(r) for r in rows]
+
+
+def fetch_comments(conn: sqlite3.Connection, task_id: str) -> list[dict]:
+    rows = conn.execute("select author, body, created_at from task_comments where task_id = ? "
+                        "order by id", (task_id,)).fetchall()
+    return [dict(r) for r in rows]
+
+
+def done_tasks(conn: sqlite3.Connection) -> list[str]:
+    rows = conn.execute("select id from tasks where status in ('done','blocked') order by rowid").fetchall()
+    return [r["id"] for r in rows]
+
+
+def bundle_for(profile_name: str | None) -> list[str]:
+    """The commands this card's profile owed, with the source that requires each one."""
+    if not profile_name or worker_brief is None:
+        return []
+    try:
+        profile = worker_brief.get_profile(ROOT, profile_name)
+        return [f"{item['command']} — {worker_brief_source(item)}"
+                for item in worker_brief.bundle_commands(profile)]
+    except (KeyError, SystemExit, OSError):
+        return []
+
+
+def worker_brief_source(item: dict) -> str:
+    source = (item.get("source") or "").strip().splitlines()
+    return source[0] if source else "profile"
+
+
+def run_exit_code(metadata: str | None) -> str | None:
+    if not metadata:
+        return None
+    try:
+        data = json.loads(metadata)
+    except (TypeError, ValueError):
+        return None
+    for key in ("command_exit_code", "exit_code"):
+        if key in data and data[key] is not None:
+            return str(data[key])
+    return None
+
+
+def iso(ts) -> str:
+    if not ts:
+        return "—"
+    try:
+        return datetime.datetime.fromtimestamp(float(ts)).astimezone().isoformat(timespec="seconds")
+    except (TypeError, ValueError, OSError):
+        return str(ts)
+
+
+def pr_links(comments: list[dict], runs: list[dict]) -> list[str]:
+    found: list[str] = []
+    for blob in [c.get("body") or "" for c in comments] + [r.get("summary") or "" for r in runs] + \
+                [r.get("metadata") or "" for r in runs]:
+        for token in blob.replace("(", " ").replace(")", " ").split():
+            if "/pull/" in token or "/issues/" in token:
+                token = token.strip(".,;\"'`")
+                if token not in found:
+                    found.append(token)
+    return found
+
+
+def spec_from_body(body: str) -> str:
+    """The issue's own words, not the brief that quoted them.
+
+    The bridge stores the rendered brief as the card body, so copying it here would duplicate the bundle
+    and the constraints in every ledger file. The binding part is the issue text; the rest is regenerable
+    with `loopgate/gates/worker_brief.py build`.
+    """
+    marker = "## Issue body (binding acceptance criteria)"
+    if marker in body:
+        tail = body.split(marker, 1)[1]
+        stop = tail.find("\n## ")
+        chunk = tail if stop == -1 else tail[:stop]
+        quoted = [line[2:] if line.startswith("> ") else ("" if line.strip() == ">" else line)
+                  for line in chunk.strip().splitlines()]
+        text = "\n".join(quoted).strip()
+        if text:
+            return text
+    goal = body.find("## Goal")
+    if goal != -1 and "## " in body[goal + 3:]:
+        tail = body[goal + len("## Goal"):]
+        stop = tail.find("\n## ")
+        text = (tail if stop == -1 else tail[:stop]).strip()
+        if text:
+            return text
+    return body
+
+
+def render(task: dict, runs: list[dict], comments: list[dict]) -> str:
+    task_id = task["id"]
+    profile = next((r.get("profile") for r in runs if r.get("profile")), None)
+    lines: list[str] = []
+    add = lines.append
+    add(f"# {task.get('title') or task_id}")
+    add("")
+    add(f"- card: `{task_id}`")
+    add(f"- assignee: `{task.get('assignee')}`")
+    add(f"- status: **{task.get('status')}**")
+    add(f"- created: {iso(task.get('created_at'))}")
+    if task.get("completed_at"):
+        add(f"- closed: {iso(task.get('completed_at'))}")
+    if task.get("workspace_path"):
+        add(f"- workspace: `{os.path.basename(str(task['workspace_path']))}`")
+    if task.get("branch_name"):
+        add(f"- branch: `{task['branch_name']}`")
+    if task.get("idempotency_key"):
+        add(f"- idempotency key: `{task['idempotency_key']}`")
+    links = pr_links(comments, runs)
+    for link in links:
+        add(f"- link: {link}")
+    add("")
+
+    add("## Spec")
+    add("")
+    body = (task.get("body") or "").strip()
+    if not body:
+        add("_no body recorded on the card_")
+    else:
+        for raw in spec_from_body(body).splitlines():
+            add(raw)
+    add("")
+
+    bundle = bundle_for(profile)
+    add("## Evidence bundle the card owed")
+    add("")
+    if bundle:
+        add(f"Profile `{profile}` requires all of these; a missing command is a REJECT at review.")
+        add("")
+        for item in bundle:
+            add(f"- `{item}`")
+    else:
+        add("_no profile bundle recorded (the card was not dispatched with a repo profile)_")
+    add("")
+
+    add("## Runs")
+    add("")
+    if not runs:
+        add("_no run recorded_")
+    else:
+        add("| run | status | outcome | started | ended | exit |")
+        add("|---|---|---|---|---|---|")
+        for run in runs:
+            add(f"| {run.get('id')} | {run.get('status')} | {run.get('outcome') or '—'} | "
+                f"{iso(run.get('started_at'))} | {iso(run.get('ended_at'))} | "
+                f"{run_exit_code(run.get('metadata')) or '—'} |")
+        add("")
+        for run in runs:
+            summary = (run.get("summary") or "").strip()
+            error = (run.get("error") or "").strip()
+            if summary or error:
+                add(f"**run {run.get('id')}**")
+                add("")
+                for raw in (summary or error).splitlines():
+                    add(f"> {raw}" if raw.strip() else ">")
+                add("")
+
+    add("## Review trail")
+    add("")
+    if not comments:
+        add("_no comments_")
+    else:
+        for comment in comments:
+            add(f"**{comment.get('author') or 'unknown'}** · {iso(comment.get('created_at'))}")
+            add("")
+            for raw in (comment.get("body") or "").splitlines():
+                add(f"> {raw}" if raw.strip() else ">")
+            add("")
+
+    add("## Verdict")
+    add("")
+    last = runs[-1] if runs else None
+    if not last:
+        add("No run has executed this card yet: the ledger records the intent, not a result.")
+    else:
+        exit_code = run_exit_code(last.get("metadata"))
+        add(f"Last run `{last.get('id')}` ended as `{last.get('status')}`"
+            + (f" with exit `{exit_code}`" if exit_code is not None else "")
+            + f" ({iso(last.get('ended_at'))}).")
+        if task.get("last_failure_error"):
+            add("")
+            add(f"Last recorded failure: `{task['last_failure_error']}`")
+    add("")
+    # No render timestamp on purpose: a clock in the artefact makes every re-render a diff, and a ledger
+    # that churns is a ledger nobody reads. The history lives in git, which already records when.
+    add("_Rendered from the board by `loopgate/gates/render_task_ledger.py`. "
+        "The board decides, the ledger remembers._")
+    add("")
+    return "\n".join(lines)
+
+
+def write_ledger(root: str, task_id: str, content: str, dry_run: bool) -> tuple[str, bool]:
+    out_dir = os.path.join(root, OUT_DIR)
+    path = os.path.join(out_dir, f"{task_id}.md")
+    previous = None
+    if os.path.exists(path):
+        with open(path, encoding="utf-8") as fh:
+            previous = fh.read()
+    if previous == content:
+        return path, False
+    if not dry_run:
+        os.makedirs(out_dir, exist_ok=True)
+        with open(path, "w", encoding="utf-8") as fh:
+            fh.write(content)
+    return path, True
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="Render board cards into backlog/<task-id>.md.")
+    ap.add_argument("task_ids", nargs="*", help="card ids, e.g. t_example")
+    ap.add_argument("--all-done", action="store_true", help="every card that is done or blocked")
+    ap.add_argument("--db", default=KANBAN_DB)
+    ap.add_argument("--root", default=ROOT)
+    ap.add_argument("--dry-run", action="store_true")
+    args = ap.parse_args(argv)
+
+    if not os.path.exists(args.db):
+        print(f"board not found: {args.db}", file=sys.stderr)
+        print(STOP_MARKER)
+        return 1
+    conn = connect(args.db)
+    ids = list(args.task_ids)
+    if args.all_done:
+        ids.extend(i for i in done_tasks(conn) if i not in ids)
+    if not ids:
+        print("nothing to render: pass card ids or --all-done", file=sys.stderr)
+        print(STOP_MARKER)
+        return 1
+
+    failed = 0
+    for task_id in ids:
+        task = fetch_task(conn, task_id)
+        if not task:
+            print(f"  {task_id} [MISSING] no such card on the board", file=sys.stderr)
+            failed += 1
+            continue
+        runs = fetch_runs(conn, task_id)
+        comments = fetch_comments(conn, task_id)
+        path, changed = write_ledger(args.root, task_id, render(task, runs, comments), args.dry_run)
+        rel = os.path.relpath(path, args.root)
+        state = "written" if changed else "unchanged"
+        if args.dry_run:
+            state = "would write" if changed else "unchanged"
+        print(f"  {task_id} [{state}] {rel} — {len(runs)} run(s), {len(comments)} comment(s)")
+    conn.close()
+    if failed:
+        print(f"cards not rendered: {failed}", file=sys.stderr)
+        print(STOP_MARKER)
+        return 1
+    print(PASS_MARKER)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

loopgate/gates/review_pr.py

@@ -0,0 +1,370 @@
+#!/usr/bin/env python3
+"""Second-level review: the whole pull request, read by an engine that did not write it.
+
+`loopgate/gates/worker_brief.py verify` proves the worker ran the bundle. It says nothing about whether the change
+is a good idea: a worker can prove every gate and still ship the wrong design. This script sends the entire
+PR diff to an independent model through `ywcrew` (the only door to the CLI agents, per AGENTS.md), asks for
+a verdict, and either prints it or posts it as a PR review.
+
+    python3 -m loopgate.gates.review_pr --profile sample-service --pr 3 --dry-run     # build the brief, dispatch nothing
+    python3 -m loopgate.gates.review_pr --profile sample-service --pr 3               # dispatch, print the verdict
+    python3 -m loopgate.gates.review_pr --profile sample-service --pr 3 --post        # also post it to the PR
+
+Verdict: PR_REVIEW_PASS_0001 (exit 0) when the reviewer accepts the change; PR_REVIEW_STOP_0001 (exit 1)
+when it asks for changes, rejects it, or the dispatch cannot be made. A reviewer that cannot be reached is
+not an approval.
+
+Cost note: `--backend` and `--model` default to `agy:gemini-3.8-flash` on purpose. The panel (`--panel`) is
+available and costs one dispatch per member; it is not the default because a review is not improved by
+paying three times for the same first look.
+"""
+
+from __future__ import annotations
+
+from loopgate.paths import TEMPLATES_DIR, project_root, gate_file
+
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+
+ROOT = project_root()
+PASS_MARKER = "PR_REVIEW_PASS_0001"
+STOP_MARKER = "PR_REVIEW_STOP_0001"
+VERDICT_RE = re.compile(r"VERDICT\s*:\s*(APPROVE|CHANGES|REJECT)", re.I)
+MAX_DIFF_CHARS = 60_000
+
+try:
+    from loopgate.gates import worker_brief  # noqa: E402
+except ImportError:  # pragma: no cover
+    worker_brief = None
+
+
+def run(cmd: list[str], stdin: str | None = None, timeout: int = 900) -> subprocess.CompletedProcess:
+    return subprocess.run(cmd, input=stdin, capture_output=True, text=True, timeout=timeout)
+
+
+def profile_or_die(name: str) -> dict:
+    if worker_brief is None:
+        sys.exit("worker_brief.py is not importable: cannot resolve a repo profile")
+    try:
+        return worker_brief.get_profile(ROOT, name)
+    except (KeyError, SystemExit):
+        print(f"unknown profile {name!r}; try one of: "
+              f"{', '.join(sorted(worker_brief.load_profiles(ROOT)['profiles']))}", file=sys.stderr)
+        raise SystemExit(1)
+
+
+def pr_meta(repo: str, pr: int) -> dict:
+    proc = run(["gh", "pr", "view", str(pr), "-R", repo, "--json",
+                "title,body,headRefName,baseRefName,headRefOid,files,additions,deletions"])
+    if proc.returncode != 0:
+        raise RuntimeError(f"gh pr view failed: {proc.stderr.strip()[:300]}")
+    return json.loads(proc.stdout)
+
+
+def pr_diff(repo: str, pr: int) -> str:
+    proc = run(["gh", "pr", "diff", str(pr), "-R", repo])
+    if proc.returncode != 0:
+        raise RuntimeError(f"gh pr diff failed: {proc.stderr.strip()[:300]}")
+    return proc.stdout
+
+
+def build_task(profile: dict, repo: str, pr: int, meta: dict, diff: str, bundle: list[str]) -> dict:
+    """A five-part task for the dispatcher. English by policy: the payload is not a chat message."""
+    files = [f.get("path") for f in (meta.get("files") or []) if f.get("path")]
+    truncated = diff[:MAX_DIFF_CHARS]
+    cut = "" if len(diff) <= MAX_DIFF_CHARS else (
+        f"\n\n[diff truncated: showing the first {MAX_DIFF_CHARS} of {len(diff)} characters]")
+    rules = "; ".join((profile.get("pr_rules") or [])[:5])
+    task = {
+        "objective": (
+            f"Review pull request #{pr} in {repo} — '{meta.get('title', '')}' — as the second level of review. "
+            f"The worker already proved the evidence bundle, so do not re-litigate whether the commands ran: "
+            f"judge the change itself. Merge base {meta.get('baseRefName')} <- head {meta.get('headRefName')} "
+            f"({meta.get('additions', '?')} added, {meta.get('deletions', '?')} removed, {len(files)} files). "
+            "Say plainly whether this should be merged."),
+        "briefing": (
+            "This repository accepts work only inside a loop with evidence: one task = one PR, the PR body "
+            "carries the mandatory commands verbatim with exit codes, and a reviewer re-runs the bundle in a "
+            "separate worktree of the head commit. Your review is the second, independent level: design, "
+            "correctness, failure modes and whether the change does what the issue asked — not the plumbing."
+            + (f" Repository PR rules: {rules}." if rules else "")
+            + (f" The pull request body:\n\n{(meta.get('body') or '')[:4000]}" if meta.get("body") else "")),
+        "locations": ("The full diff is below and it is the whole change. Files touched: "
+                      + (", ".join(files[:40]) if files else "(none reported)")
+                      + ". The repository's own gates live in loopgate/gates/ (check_loop.py, assert_dims.py, "
+                        "regressions.py) and configs/repo_profiles.json."),
+        "constraints": (
+            "Read-only: propose changes, never rewrite the code. Do not comment on formatting that the "
+            "project's own linter accepts. Do not invent files or APIs you cannot see in the diff. If the "
+            "diff is truncated, say which part you could not see instead of guessing. Do not discuss the "
+            "evidence bundle's completeness — another gate covers that."),
+        "output_contract": (
+            "Markdown, at most 400 words. Sections: 'Findings' (each with file:line, severity "
+            "blocker/major/minor, and the consequence for a user or operator), 'Missing tests or evidence', "
+            "'Questions for the author'. The last line of your reply must be exactly "
+            "'VERDICT: APPROVE' or 'VERDICT: CHANGES' or 'VERDICT: REJECT' — nothing after it."),
+    }
+    payload = "\n\n".join([f"## Objective\n{task['objective']}", f"## Diff\n```diff\n{truncated}\n```{cut}"])
+    # The dispatcher can hand the reviewer the real files, but it resolves globs against the dispatcher's
+    # own cwd — and the reviewed repository is usually a different checkout. A path that does not exist
+    # there aborts the whole dispatch, so only files this tree actually has are offered; the diff in the
+    # prompt is what the review is based on either way.
+    local = [f for f in (files or []) if os.path.exists(os.path.join(ROOT, f))]
+    return {"task": task, "diff": payload, "files": local or None}
+
+
+def dispatch(spec: dict, backend: str, model: str | None, panel: bool) -> tuple[str, str]:
+    """Send the task through ywcrew and return (raw_result_text, run_reference)."""
+    body = {"mode": "read-only", "label": spec["task"]["objective"][:60],
+            "task": dict(spec["task"]), "files": spec.get("files") or []}
+    with tempfile.NamedTemporaryFile("w", suffix=".json", delete=False, encoding="utf-8") as fh:
+        json.dump(body, fh, ensure_ascii=False)
+        task_path = fh.name
+    try:
+        if panel:
+            cmd = ["ywcrew", "panel", "--task-file", task_path]
+        else:
+            body["backend"] = backend
+            if model:
+                body["model"] = model
+            with open(task_path, "w", encoding="utf-8") as fh:
+                json.dump(body, fh, ensure_ascii=False)
+            cmd = ["ywcrew", "run", "--task-file", task_path]
+        proc = run(cmd)
+        if proc.returncode != 0:
+            raise RuntimeError(f"{' '.join(cmd[:2])} failed: {(proc.stderr or proc.stdout).strip()[:300]}")
+        out = proc.stdout.strip()
+        run_id = None
+        try:
+            data = json.loads(out)
+            run_id = data.get("runId") or data.get("run_id") or (data.get("run") or {}).get("id")
+        except json.JSONDecodeError:
+            match = re.search(r"\b(run_[A-Za-z0-9_-]+|[0-9a-f]{8,})\b", out)
+            run_id = match.group(1) if match else None
+        if not run_id:
+            raise RuntimeError(f"could not read a run id from ywcrew output: {out[:300]}")
+        # `ywcrew result` prints JSON by default; the flag that would ask for it does not exist and the
+        # earlier version failed on it after a review had already been paid for.
+        result = run(["ywcrew", "result", run_id, "--wait", "--timeout", "1200"], timeout=1800)
+        text = result.stdout or result.stderr
+        if result.returncode != 0:
+            raise RuntimeError(f"ywcrew result failed for {run_id}: {text.strip()[:300]}")
+        return text, run_id
+    finally:
+        os.unlink(task_path)
+
+
+def extract_text(raw: str) -> str:
+    """The reviewer's prose, whichever shape the dispatcher used to wrap it."""
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        return raw
+    chunks: list[str] = []
+
+    def walk(node):
+        if isinstance(node, dict):
+            for key in ("output", "text", "content", "result", "summary"):
+                value = node.get(key)
+                if isinstance(value, str) and len(value) > 40:
+                    chunks.append(value)
+            for value in node.values():
+                if isinstance(value, (dict, list)):
+                    walk(value)
+        elif isinstance(node, list):
+            for item in node:
+                walk(item)
+
+    walk(data)
+    return "\n\n".join(chunks) if chunks else raw
+
+
+def verdict_of(text: str) -> str | None:
+    found = VERDICT_RE.findall(text)
+    return found[-1].upper() if found else None
+
+
+def post_review(repo: str, pr: int, body: str, verdict: str) -> str:
+    with tempfile.NamedTemporaryFile("w", suffix=".md", delete=False, encoding="utf-8") as fh:
+        fh.write(body)
+        path = fh.name
+    try:
+        flag = {"APPROVE": "--approve", "CHANGES": "--request-changes"}.get(verdict, "--comment")
+        proc = run(["gh", "pr", "review", str(pr), "-R", repo, flag, "--body-file", path])
+        if proc.returncode == 0:
+            return f"posted as {flag}"
+        message = (proc.stderr or proc.stdout).strip()
+        # GitHub refuses a formal approval on your own pull request. That is a rule about the author, not a
+        # failure of the review, so the verdict still lands — as a comment, with the reason kept.
+        if "your own pull request" in message:
+            proc = run(["gh", "pr", "review", str(pr), "-R", repo, "--comment", "--body-file", path])
+            if proc.returncode == 0:
+                return (f"posted as --comment (GitHub refuses {flag} on your own pull request; the verdict "
+                        f"is unchanged: {verdict})")
+        return f"failed: {message[:200]}"
+    finally:
+        os.unlink(path)
+
+
+def selftest() -> int:
+    """Offline unit test: assert parser verdict mapping and verify that missing verdict never posts."""
+    # The selftest must pass in any tree: the published one ships `sample-service`, the working one ships
+    # the real profiles. Hardcoding a profile name made the test pass only where that name happened to exist.
+    profiles = sorted((worker_brief.load_profiles(ROOT) if worker_brief else {}) or {})
+    if not profiles:
+        print("selftest: no repository profile to parse the fixtures with", file=sys.stderr)
+        return 1
+    profile_name = profiles[0]
+    fixtures = [
+        ("configs/fixtures/review_approve.json", "APPROVE", PASS_MARKER, 0),
+        ("configs/fixtures/review_changes.json", "CHANGES", STOP_MARKER, 1),
+        ("configs/fixtures/review_no_verdict.json", None, STOP_MARKER, 1),
+    ]
+    for path, expected_verdict, expected_marker, expected_rc in fixtures:
+        full_path = os.path.join(TEMPLATES_DIR, path)
+        if not os.path.exists(full_path):
+            print(f"selftest: missing fixture {path}", file=sys.stderr)
+            return 1
+        raw = open(full_path, encoding="utf-8").read()
+        text = extract_text(raw)
+        verdict = verdict_of(text)
+        if verdict != expected_verdict:
+            print(f"selftest failed for {path}: expected verdict {expected_verdict!r}, got {verdict!r}", file=sys.stderr)
+            return 1
+    # Run main() on all three fixtures to assert full end-to-end exit code and output
+    for path, expected_verdict, expected_marker, expected_rc in fixtures:
+        full_path = os.path.join(TEMPLATES_DIR, path)
+        proc = subprocess.run(
+            [sys.executable, "-m", "loopgate.gates.review_pr", "--profile", profile_name, "--pr", "0", "--result-file", full_path],
+            capture_output=True, text=True
+        )
+        if proc.returncode != expected_rc:
+            print(f"selftest failed for {path}: expected rc {expected_rc}, got {proc.returncode}. Output:\n{proc.stdout}\n{proc.stderr}", file=sys.stderr)
+            return 1
+        if expected_marker not in proc.stdout and expected_marker not in proc.stderr:
+            print(f"selftest failed for {path}: marker {expected_marker} not found in output", file=sys.stderr)
+            return 1
+        if expected_verdict is None:
+            if "the reviewer did not return a VERDICT line" not in proc.stderr:
+                print(f"selftest failed for {path}: did not name missing verdict line in stderr", file=sys.stderr)
+                return 1
+
+    # Assert that --post is NOT attempted when the verdict is missing
+    proc_post = subprocess.run(
+        [sys.executable, "-m", "loopgate.gates.review_pr", "--profile", profile_name, "--pr", "0",
+         "--result-file", os.path.join(TEMPLATES_DIR, "configs", "fixtures", "review_no_verdict.json"), "--post"],
+        capture_output=True, text=True
+    )
+    if proc_post.returncode != 1:
+        print("selftest failed: --post with missing verdict must exit 1", file=sys.stderr)
+        return 1
+    if "post:" in proc_post.stdout or "post:" in proc_post.stderr:
+        print("selftest failed: --post attempted despite missing verdict", file=sys.stderr)
+        return 1
+
+    print("selftest: all fixture verdicts and stop conditions verified")
+    print(PASS_MARKER)
+    return 0
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="Second-level review of a pull request via ywcrew.")
+    # Required in practice, but validated after the --selftest branch: a bare `--selftest` must be able to
+    # run without inventing a repository, while every other invocation still fails fast instead of
+    # defaulting to some arbitrary profile and pull request.
+    ap.add_argument("--profile", help="repo profile that names the repository (required unless --selftest)")
+    ap.add_argument("--pr", type=int, help="pull request number to review (required unless --selftest)")
+    ap.add_argument("--backend", default="agy")
+    ap.add_argument("--model", default="gemini-3.8-flash")
+    ap.add_argument("--panel", action="store_true", help="use ywcrew panel instead of one backend")
+    ap.add_argument("--post", action="store_true", help="post the verdict to the PR as a review")
+    ap.add_argument("--dry-run", action="store_true",
+                    help="print the brief, dispatch nothing (ignored with --result-file: nothing is dispatched)")
+    ap.add_argument("--diff-file", help="review a diff from a file instead of asking gh (offline)")
+    ap.add_argument("--result-file", help="parse an existing `ywcrew result` JSON instead of dispatching")
+    ap.add_argument("--selftest", action="store_true", help="run offline fixture assertions, then exit")
+    args = ap.parse_args(argv)
+
+    if args.selftest:
+        return selftest()
+
+    if not args.profile or args.pr is None:
+        ap.error("--profile and --pr are required unless --selftest is given")
+
+    profile = profile_or_die(args.profile)
+    repo = profile["repo"]
+
+    if args.result_file:
+        try:
+            raw = open(args.result_file, encoding="utf-8").read()
+        except OSError as exc:
+            print(f"cannot read the result file: {exc}", file=sys.stderr)
+            print(STOP_MARKER)
+            return 1
+        run_id = "from --result-file"
+    else:
+        if not shutil.which("gh") and not args.diff_file:
+            print("gh is not installed: pass --diff-file or install the GitHub CLI", file=sys.stderr)
+            print(STOP_MARKER)
+            return 1
+        try:
+            if args.diff_file:
+                diff = open(args.diff_file, encoding="utf-8", errors="replace").read()
+                meta = {"title": os.path.basename(args.diff_file), "files": [], "baseRefName": "?",
+                        "headRefName": "?"}
+            else:
+                meta = pr_meta(repo, args.pr)
+                diff = pr_diff(repo, args.pr)
+        except (RuntimeError, OSError) as exc:
+            print(f"cannot read the pull request: {exc}", file=sys.stderr)
+            print(STOP_MARKER)
+            return 1
+
+        bundle = [i["command"] for i in (worker_brief.bundle_commands(profile) if worker_brief else [])]
+        spec = build_task(profile, repo, args.pr, meta, diff, bundle)
+
+        if args.dry_run:
+            print(spec["diff"])
+            print()
+            print(f"--- not dispatched. backend={args.backend}:{args.model} panel={args.panel} ---")
+            print(PASS_MARKER)
+            return 0
+
+        try:
+            raw, run_id = dispatch(spec, args.backend, args.model, args.panel)
+        except (RuntimeError, OSError, subprocess.SubprocessError) as exc:
+            print(f"dispatch failed: {exc}", file=sys.stderr)
+            print(STOP_MARKER)
+            return 1
+
+    text = extract_text(raw)
+    verdict = verdict_of(text)
+    print(text.strip()[:6000])
+    print()
+    print(f"review run: {run_id}")
+    if not verdict:
+        print("the reviewer did not return a VERDICT line: an unreadable review is not an approval",
+              file=sys.stderr)
+        print(STOP_MARKER)
+        return 1
+    print(f"verdict: {verdict}")
+    if args.post:
+        print("post: " + post_review(repo, args.pr,
+                                     f"Second-level review ({args.backend}"
+                                     f"{':' + args.model if args.model else ''} via ywcrew)\n\n"
+                                     + text.strip(), verdict))
+    if verdict == "APPROVE":
+        print(PASS_MARKER)
+        return 0
+    print(STOP_MARKER)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())