blackroad-operating-system/docs/PR_ACTION_INTELLIGENCE.md

PR Action Intelligence System

Phase Q2 - Autonomous GitHub PR Management

---

Overview

The PR Action Intelligence System is BlackRoad OS's autonomous GitHub automation layer that eliminates manual PR interactions. Instead of clicking buttons like "Update Branch," "Commit Suggestion," or "Rerun Checks," these actions are intelligently queued, prioritized, and executed by the Operator Engine.

Architecture

┌─────────────────────────────────────────┐
│         GitHub PR Interface             │
│  (Comments, Reviews, Checks, Labels)    │
└─────────────────┬───────────────────────┘
                  │ Webhooks
                  ↓
┌─────────────────────────────────────────┐
│      GitHub Webhook Handler             │
│  (operator_engine/github_webhooks.py)   │
└─────────────────┬───────────────────────┘
                  │ Event Normalization
                  ↓
┌─────────────────────────────────────────┐
│        PR Action Queue                  │
│  (operator_engine/pr_actions/)          │
│  - Prioritization                       │
│  - Deduplication                        │
│  - Rate Limiting                        │
│  - Retry Logic                          │
└─────────────────┬───────────────────────┘
                  │ Action Execution
                  ↓
┌─────────────────────────────────────────┐
│         Action Handlers                 │
│  - resolve_comment.py                   │
│  - commit_suggestion.py                 │
│  - update_branch.py                     │
│  - rerun_checks.py                      │
│  - open_issue.py                        │
│  - add_label.py                         │
│  - merge_pr.py                          │
└─────────────────┬───────────────────────┘
                  │ GitHub API Calls
                  ↓
┌─────────────────────────────────────────┐
│         GitHub API Client               │
│  (operator_engine/github_client.py)     │
└─────────────────────────────────────────┘

Components

1. GitHub Webhook Handler

File: operator_engine/github_webhooks.py

Receives GitHub webhook events and maps them to PR actions.

Supported Events:

• pull_request - PR opened, synchronized, labeled, etc.
• pull_request_review - Review submitted
• pull_request_review_comment - Review comment created
• issue_comment - Comment on PR
• check_suite - Check suite completed
• check_run - Individual check completed
• workflow_run - Workflow completed

Event Mapping:

# Example: PR labeled with "claude-auto"
Event: pull_request.labeled
→ Action: ADD_TO_MERGE_QUEUE
→ Priority: HIGH
→ Triggered by: webhook:labeled:claude-auto

2. PR Action Queue

File: operator_engine/pr_actions/action_queue.py

Priority-based queue with intelligent action management.

Features:

• Priority-based execution - Critical actions (security, hotfixes) first
• Deduplication - Identical actions are merged
• Rate limiting - Max 10 actions per repo per minute
• Automatic retry - Exponential backoff (2s, 4s, 8s)
• Concurrent workers - 5 workers processing actions in parallel

Queue States:

• QUEUED - Waiting for execution
• PROCESSING - Currently being executed
• COMPLETED - Successfully completed
• FAILED - Failed after max retries
• CANCELLED - Manually cancelled
• RETRYING - Retrying after failure

3. Action Types

File: operator_engine/pr_actions/action_types.py

Defines all possible PR actions.

Action Categories:

Comment Actions:

• RESOLVE_COMMENT - Mark a comment thread as resolved
• CREATE_COMMENT - Add a comment to PR
• EDIT_COMMENT - Edit existing comment
• DELETE_COMMENT - Delete a comment

Code Suggestion Actions:

• APPLY_SUGGESTION - Apply a single code suggestion
• COMMIT_SUGGESTION - Commit a suggestion with custom message
• BATCH_SUGGESTIONS - Apply multiple suggestions at once

Branch Actions:

• UPDATE_BRANCH - Merge base branch into PR branch
• REBASE_BRANCH - Rebase PR branch on base branch
• SQUASH_COMMITS - Squash commits in PR

Check Actions:

• RERUN_CHECKS - Rerun all CI/CD checks
• RERUN_FAILED_CHECKS - Rerun only failed checks
• SKIP_CHECKS - Skip checks (admin only)

Review Actions:

• REQUEST_REVIEW - Request review from user/team
• APPROVE_PR - Approve the PR
• REQUEST_CHANGES - Request changes
• DISMISS_REVIEW - Dismiss a review

Label Actions:

• ADD_LABEL - Add labels to PR
• REMOVE_LABEL - Remove labels from PR
• SYNC_LABELS - Auto-sync labels based on file changes

Merge Actions:

• MERGE_PR - Merge PR (default method)
• SQUASH_MERGE - Squash and merge
• REBASE_MERGE - Rebase and merge
• ADD_TO_MERGE_QUEUE - Add PR to merge queue
• REMOVE_FROM_MERGE_QUEUE - Remove PR from merge queue

Issue Actions:

• OPEN_ISSUE - Create a new issue
• CLOSE_ISSUE - Close an issue
• LINK_ISSUE - Link issue to PR

4. Action Handlers

Directory: operator_engine/pr_actions/handlers/

Each handler implements the logic for a specific action type.

Base Handler Pattern:

class BaseHandler(ABC):
    async def execute(self, action: PRAction) -> Dict[str, Any]:
        """Execute the action"""
        pass

    async def validate(self, action: PRAction) -> bool:
        """Validate before execution"""
        pass

    async def get_github_client(self):
        """Get authenticated GitHub client"""
        pass

Example Handler: Update Branch

# File: handlers/update_branch.py

async def execute(self, action: PRAction) -> Dict[str, Any]:
    gh = await self.get_github_client()

    # Get PR details
    pr = await gh.get_pull_request(
        action.repo_owner, action.repo_name, action.pr_number
    )

    # Check if branch is behind
    is_behind = await gh.is_branch_behind(
        action.repo_owner, action.repo_name,
        pr["head"]["ref"], pr["base"]["ref"]
    )

    if not is_behind:
        return {"updated": False, "reason": "already_up_to_date"}

    # Update the branch
    result = await gh.update_branch(
        action.repo_owner, action.repo_name,
        action.pr_number, method="merge"
    )

    return {
        "updated": True,
        "commit_sha": result.get("sha")
    }

5. GitHub API Client

File: operator_engine/github_client.py

Async HTTP client for GitHub REST API.

Features:

• Authentication - Bearer token via GITHUB_TOKEN
• Rate limiting - Tracks and respects GitHub rate limits
• Auto-retry - Retries on 429 (rate limit exceeded)
• Type safety - Full type hints for all operations

Example Usage:

gh = await get_github_client()

# Get a PR
pr = await gh.get_pull_request("owner", "repo", 123)

# Update branch
await gh.update_branch("owner", "repo", 123)

# Add labels
await gh.add_labels("owner", "repo", 123, ["backend", "tests"])

# Merge PR
await gh.merge_pull_request("owner", "repo", 123, merge_method="squash")

Integration with Prism Console

The PR Action Queue integrates with the Prism Console Merge Dashboard, providing:

• Real-time queue statistics - See what's queued, processing, completed, failed
• PR action history - Full audit trail of all actions taken
• Manual triggers - Manually trigger actions when needed
• Logs and debugging - View execution logs and error messages

API Endpoints:

# Queue statistics
GET /api/operator/queue/stats

# PR action history
GET /api/operator/queue/pr/{owner}/{repo}/{pr_number}

# Action status
GET /api/operator/queue/action/{action_id}

# Cancel action
POST /api/operator/queue/action/{action_id}/cancel

# Health check
GET /api/operator/health

Workflow

Typical PR Lifecycle with Automation

1. PR Opened (by Claude)

   • Webhook: pull_request.opened
   • Action: SYNC_LABELS (auto-label based on files)
   • Priority: BACKGROUND

2. New Commits Pushed

   • Webhook: pull_request.synchronized
   • Action: UPDATE_BRANCH (if behind base)
   • Priority: HIGH

3. Labeled with "claude-auto"

   • Webhook: pull_request.labeled
   • Action: ADD_TO_MERGE_QUEUE
   • Priority: HIGH

4. Review Comment with "/update-branch"

   • Webhook: issue_comment.created
   • Action: UPDATE_BRANCH
   • Priority: HIGH

5. Check Suite Failed

   • Webhook: check_suite.completed
   • Action: RERUN_FAILED_CHECKS
   • Priority: CRITICAL

6. All Checks Pass + Approved

   • Webhook: pull_request_review.submitted
   • Action: MERGE_PR
   • Priority: CRITICAL

Configuration

Environment Variables

# Required
GITHUB_TOKEN=ghp_...                    # GitHub Personal Access Token
GITHUB_WEBHOOK_SECRET=your-secret       # Webhook signature validation

# Optional
OPERATOR_WEBHOOK_URL=https://...        # Operator webhook endpoint
MAX_QUEUE_WORKERS=5                     # Number of concurrent workers
MAX_ACTIONS_PER_REPO=10                 # Rate limit per repo
ACTION_RETRY_MAX=3                      # Max retry attempts

GitHub Webhook Setup

1. Go to repository Settings → Webhooks

2. Add webhook:

   • Payload URL: https://your-domain.com/api/operator/webhooks/github
   • Content type: application/json
   • Secret: Your GITHUB_WEBHOOK_SECRET
   • Events: Select individual events:
     • Pull requests
     • Pull request reviews
     • Pull request review comments
     • Issue comments
     • Check suites
     • Check runs
     • Workflow runs

3. Save webhook

Security

Webhook Signature Verification

All incoming webhooks are verified using HMAC-SHA256:

expected_signature = "sha256=" + hmac.new(
    webhook_secret.encode(),
    payload,
    hashlib.sha256
).hexdigest()

if not hmac.compare_digest(expected_signature, received_signature):
    raise HTTPException(status_code=401, detail="Invalid signature")

Rate Limiting

Per-repo rate limiting prevents abuse:

• Max 10 actions per repo per minute
• Exponential backoff on retries
• GitHub API rate limits respected (5000/hour)

Action Validation

All actions are validated before execution:

• Required parameters present
• PR exists and is open
• User has necessary permissions
• Branch is not protected (for destructive operations)

Monitoring

Logs

All actions are logged with structured logging:

logger.info(
    f"Executing {action.action_type.value} for "
    f"{action.repo_owner}/{action.repo_name}#{action.pr_number} "
    f"(attempt {action.attempts}/{action.max_attempts})"
)

Metrics

Track queue performance:

• Actions per minute
• Success/failure rate
• Average execution time
• Queue depth over time

Alerts

Set up alerts for:

• High failure rate (>20%)
• Queue depth > 50
• Webhook signature failures
• GitHub API rate limit approaching

Troubleshooting

Common Issues

1. Actions not being queued

• Check webhook is configured correctly
• Verify GITHUB_WEBHOOK_SECRET matches
• Check webhook delivery logs in GitHub

2. Actions failing

• Check GITHUB_TOKEN has necessary permissions
• Verify GitHub API rate limit not exceeded
• Review action execution logs

3. Queue not processing

• Check queue is running: GET /api/operator/health
• Restart queue workers
• Check for exceptions in logs

4. Duplicate actions

• Deduplication should prevent this
• Check if webhooks are firing multiple times
• Review queue logs for details

Debug Mode

Enable debug logging:

import logging

logging.getLogger('operator_engine').setLevel(logging.DEBUG)

Manual Action Triggering

Trigger actions via API:

curl -X POST https://your-domain.com/api/operator/queue/enqueue \
  -H "Content-Type: application/json" \
  -d '{
    "action_type": "update_branch",
    "repo_owner": "blackboxprogramming",
    "repo_name": "BlackRoad-Operating-System",
    "pr_number": 123,
    "params": {"method": "merge"}
  }'

Future Enhancements

• GraphQL Support - Use GitHub GraphQL API for advanced operations
• Batch Operations - Apply suggestions in batches
• ML-based Prioritization - Learn from past actions to optimize priority
• Cross-repo Actions - Actions that span multiple repositories
• Custom Webhooks - Trigger external services
• Action Scheduling - Schedule actions for specific times
• Rollback Support - Undo actions if needed

---

Status: ✅ Production Ready (Phase Q2) Maintainer: @alexa-amundson Last Updated: 2025-11-18