feat(agent): post self-review summary as PR comment (#263)

After the self-review phase completes, the agent writes a structured
summary of findings to `.self-review-summary.md`. The pipeline reads
this file, posts it as a PR comment via `gh pr comment`, then deletes
it so it never appears in the PR diff. Fail-open: if the file is
missing or the comment fails to post, the pipeline continues normally.

Author: bgagent

agent/src/pipeline.py

@@ -23,6 +23,7 @@
     _extract_agent_notes,
     ensure_committed,
     ensure_pr,
+    post_self_review_comment,
     verify_build,
     verify_lint,
 )
@@ -664,6 +665,10 @@ def _on_trace_truncated(max_bytes: int, first_dropped: int) -> None:
             if pr_url:
                 progress.write_agent_milestone("pr_created", pr_url)
 
+            # Post self-review summary as PR comment (if self-review ran and produced findings)
+            if pr_url and review_result is not None:
+                post_self_review_comment(setup.repo_dir, pr_url, config)
+
             # Memory write — capture task episode and repo learnings
             memory_written = False
             effective_memory_id = memory_id or os.environ.get("MEMORY_ID", "")

agent/src/post_hooks.py

@@ -327,6 +327,68 @@ def ensure_pr(
         return None
 
 
+def post_self_review_comment(repo_dir: str, pr_url: str, config: TaskConfig) -> bool:
+    """Post the self-review summary as a PR comment.
+
+    Reads the summary file written by the self-review agent, formats it as a
+    comment, and posts it via `gh pr comment`. Fail-open: exceptions are logged
+    but never propagated.
+
+    Returns True if a comment was posted, False otherwise.
+    """
+    from self_review import read_self_review_summary
+
+    try:
+        summary = read_self_review_summary(repo_dir)
+    except Exception as e:
+        log("WARN", f"post_self_review_comment: failed to read summary: {type(e).__name__}: {e}")
+        return False
+
+    if not summary:
+        log("POST", "post_self_review_comment: no summary file found — skipping")
+        return False
+
+    # Extract PR number from URL (e.g. https://github.com/owner/repo/pull/123)
+    match = re.search(r"/pull/(\d+)", pr_url)
+    if not match:
+        log("WARN", f"post_self_review_comment: could not extract PR number from {pr_url}")
+        return False
+    pr_number = match.group(1)
+
+    comment_body = f"## \U0001f50d Self-Review Summary\n\n{summary}"
+
+    try:
+        result = subprocess.run(
+            [
+                "gh",
+                "pr",
+                "comment",
+                pr_number,
+                "--repo",
+                config.repo_url,
+                "--body",
+                comment_body,
+            ],
+            cwd=repo_dir,
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+        if result.returncode == 0:
+            log("POST", f"Self-review summary posted as comment on PR #{pr_number}")
+            return True
+        stderr = result.stderr.strip()[:200] if result.stderr else ""
+        log(
+            "WARN",
+            f"post_self_review_comment: gh pr comment failed "
+            f"(rc={result.returncode}): {stderr}",
+        )
+        return False
+    except (subprocess.TimeoutExpired, OSError) as e:
+        log("WARN", f"post_self_review_comment: {type(e).__name__}: {e}")
+        return False
+
+
 def _extract_agent_notes(repo_dir: str, branch: str, config: TaskConfig) -> str | None:
     """Extract the "## Agent notes" section from the PR body.
 

agent/src/prompts/self_review.py

@@ -37,4 +37,25 @@
 concrete bug or security issue.
 - Keep fixes minimal and focused. Each fix should be a separate commit with a \
 clear message.
+
+## Summary output
+
+After completing your review (whether you made fixes or not), write a file \
+`.self-review-summary.md` in the repository root with your findings in this format:
+
+```markdown
+### Self-Review Summary
+
+**Findings:** <number of issues found>
+**Fixes applied:** <number of fixes committed>
+
+#### Issues found
+
+- <category>: <brief description of issue> — <fixed | not fixed (reason)>
+```
+
+If no issues were found, write the file with: "No issues found — code looks good."
+
+This file is a pipeline artifact and will be deleted automatically — it will NOT \
+appear in the pull request.
 """

agent/src/self_review.py

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
+import os
 import subprocess
 from typing import TYPE_CHECKING
 
@@ -196,3 +198,42 @@ def run_self_review(
         f"status={review_result.status} turns={review_result.turns}",
     )
     return review_result
+
+
+_SUMMARY_FILENAME = ".self-review-summary.md"
+
+
+def read_self_review_summary(repo_dir: str) -> str | None:
+    """Read and delete the self-review summary file.
+
+    The self-review agent writes `.self-review-summary.md` in the repo root.
+    This function reads the content, removes the file (so it never appears in
+    the PR), and returns the content. Returns None if the file doesn't exist.
+    """
+    summary_path = os.path.join(repo_dir, _SUMMARY_FILENAME)
+    if not os.path.isfile(summary_path):
+        return None
+
+    try:
+        with open(summary_path) as f:
+            content = f.read()
+    except OSError as e:
+        log("WARN", f"self_review: failed to read summary file: {type(e).__name__}: {e}")
+        return None
+
+    # Remove the file so it doesn't end up in the PR
+    try:
+        os.remove(summary_path)
+    except OSError as e:
+        log("WARN", f"self_review: failed to delete summary file: {type(e).__name__}: {e}")
+
+    # If the file was staged by the agent, unstage it
+    with contextlib.suppress(subprocess.TimeoutExpired, OSError):
+        subprocess.run(
+            ["git", "rm", "--cached", "--ignore-unmatch", "-f", _SUMMARY_FILENAME],
+            cwd=repo_dir,
+            capture_output=True,
+            timeout=30,
+        )
+
+    return content.strip() if content.strip() else None

agent/tests/test_self_review.py

@@ -1,9 +1,17 @@
 """Unit tests for self_review.py — self-review orchestration module."""
 
+import os
 from unittest.mock import MagicMock, patch
 
 from models import AgentResult, RepoSetup, TaskConfig
-from self_review import _MAX_DIFF_CHARS, _get_diff, _truncate_diff, run_self_review
+from self_review import (
+    _MAX_DIFF_CHARS,
+    _SUMMARY_FILENAME,
+    _get_diff,
+    _truncate_diff,
+    read_self_review_summary,
+    run_self_review,
+)
 
 
 def _make_config(**overrides) -> TaskConfig:
@@ -314,3 +322,163 @@ def test_works_with_unlimited_budget(self, mock_asyncio_run, mock_diff):
         result = run_self_review(config, setup, agent_result, trajectory, progress)
         assert result is not None
         assert result.status == "success"
+
+
+class TestReadSelfReviewSummary:
+    """Tests for read_self_review_summary — reads and cleans up the summary file."""
+
+    def test_returns_content_when_file_exists(self, tmp_path):
+        summary_content = (
+            "### Self-Review Summary\n\n"
+            "**Findings:** 2\n"
+            "**Fixes applied:** 1\n\n"
+            "#### Issues found\n\n"
+            "- Security: hardcoded token — fixed\n"
+            "- Style: inconsistent naming — not fixed (cosmetic)\n"
+        )
+        (tmp_path / _SUMMARY_FILENAME).write_text(summary_content)
+
+        result = read_self_review_summary(str(tmp_path))
+
+        assert result == summary_content.strip()
+
+    def test_returns_none_when_file_missing(self, tmp_path):
+        result = read_self_review_summary(str(tmp_path))
+        assert result is None
+
+    def test_deletes_file_after_reading(self, tmp_path):
+        (tmp_path / _SUMMARY_FILENAME).write_text("No issues found — code looks good.")
+
+        read_self_review_summary(str(tmp_path))
+
+        assert not (tmp_path / _SUMMARY_FILENAME).exists()
+
+    def test_returns_none_for_empty_file(self, tmp_path):
+        (tmp_path / _SUMMARY_FILENAME).write_text("   \n\n  ")
+
+        result = read_self_review_summary(str(tmp_path))
+
+        assert result is None
+
+    def test_returns_none_for_whitespace_only(self, tmp_path):
+        (tmp_path / _SUMMARY_FILENAME).write_text("\t\n ")
+
+        result = read_self_review_summary(str(tmp_path))
+
+        assert result is None
+
+    @patch("self_review.subprocess.run")
+    def test_runs_git_rm_cached_for_cleanup(self, mock_run, tmp_path):
+        (tmp_path / _SUMMARY_FILENAME).write_text("Some findings")
+        mock_run.return_value = MagicMock(returncode=0)
+
+        read_self_review_summary(str(tmp_path))
+
+        mock_run.assert_called_once_with(
+            ["git", "rm", "--cached", "--ignore-unmatch", "-f", _SUMMARY_FILENAME],
+            cwd=str(tmp_path),
+            capture_output=True,
+            timeout=30,
+        )
+
+    @patch("self_review.subprocess.run", side_effect=OSError("git not found"))
+    def test_git_rm_failure_does_not_block(self, mock_run, tmp_path):
+        (tmp_path / _SUMMARY_FILENAME).write_text("Findings here")
+
+        # Should not raise even if git rm fails
+        result = read_self_review_summary(str(tmp_path))
+
+        assert result == "Findings here"
+
+
+class TestPostSelfReviewComment:
+    """Tests for post_hooks.post_self_review_comment."""
+
+    def test_posts_comment_on_success(self, tmp_path):
+        from post_hooks import post_self_review_comment
+
+        (tmp_path / _SUMMARY_FILENAME).write_text("**Findings:** 1\n**Fixes applied:** 1")
+
+        config = MagicMock()
+        config.repo_url = "owner/repo"
+        pr_url = "https://github.com/owner/repo/pull/42"
+
+        with patch("post_hooks.subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+            result = post_self_review_comment(str(tmp_path), pr_url, config)
+
+        assert result is True
+        call_args = mock_run.call_args[0][0]
+        assert call_args[0:3] == ["gh", "pr", "comment"]
+        assert "42" in call_args
+        assert "owner/repo" in call_args
+
+    def test_returns_false_when_no_summary(self, tmp_path):
+        from post_hooks import post_self_review_comment
+
+        config = MagicMock()
+        config.repo_url = "owner/repo"
+        pr_url = "https://github.com/owner/repo/pull/42"
+
+        result = post_self_review_comment(str(tmp_path), pr_url, config)
+        assert result is False
+
+    def test_returns_false_on_invalid_pr_url(self, tmp_path):
+        from post_hooks import post_self_review_comment
+
+        (tmp_path / _SUMMARY_FILENAME).write_text("Some findings")
+
+        config = MagicMock()
+        config.repo_url = "owner/repo"
+        pr_url = "https://github.com/owner/repo/issues/42"
+
+        result = post_self_review_comment(str(tmp_path), pr_url, config)
+        assert result is False
+
+    def test_returns_false_on_gh_failure(self, tmp_path):
+        from post_hooks import post_self_review_comment
+
+        (tmp_path / _SUMMARY_FILENAME).write_text("**Findings:** 1")
+
+        config = MagicMock()
+        config.repo_url = "owner/repo"
+        pr_url = "https://github.com/owner/repo/pull/99"
+
+        with patch("post_hooks.subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(returncode=1, stdout="", stderr="not found")
+            result = post_self_review_comment(str(tmp_path), pr_url, config)
+
+        assert result is False
+
+    def test_fail_open_on_exception(self, tmp_path):
+        from post_hooks import post_self_review_comment
+
+        (tmp_path / _SUMMARY_FILENAME).write_text("**Findings:** 1")
+
+        config = MagicMock()
+        config.repo_url = "owner/repo"
+        pr_url = "https://github.com/owner/repo/pull/5"
+
+        with patch("post_hooks.subprocess.run", side_effect=OSError("network error")):
+            result = post_self_review_comment(str(tmp_path), pr_url, config)
+
+        assert result is False
+
+    def test_comment_body_includes_header(self, tmp_path):
+        from post_hooks import post_self_review_comment
+
+        (tmp_path / _SUMMARY_FILENAME).write_text("**Findings:** 0\nNo issues.")
+
+        config = MagicMock()
+        config.repo_url = "owner/repo"
+        pr_url = "https://github.com/owner/repo/pull/7"
+
+        with patch("post_hooks.subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+            post_self_review_comment(str(tmp_path), pr_url, config)
+
+        call_args = mock_run.call_args[0][0]
+        body_idx = call_args.index("--body") + 1
+        body = call_args[body_idx]
+        assert "Self-Review Summary" in body
+        assert "**Findings:** 0" in body