From e02a21dc06dac1b698165f96bd08c4daef53766d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 3 Feb 2026 16:28:15 +0000 Subject: [PATCH 1/5] Initial plan From 99c753501aa36fe4b9a6537ce6d0514b812b3f89 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 3 Feb 2026 16:31:21 +0000 Subject: [PATCH 2/5] Add PR handler workflow and management documentation Co-authored-by: blackboxprogramming <118287761+blackboxprogramming@users.noreply.github.com> --- .github/workflows/pr-handler.yml | 312 +++++++++++++++++++++++++++ PR_MANAGEMENT.md | 348 +++++++++++++++++++++++++++++++ 2 files changed, 660 insertions(+) create mode 100644 .github/workflows/pr-handler.yml create mode 100644 PR_MANAGEMENT.md diff --git a/.github/workflows/pr-handler.yml b/.github/workflows/pr-handler.yml new file mode 100644 index 0000000..8e60617 --- /dev/null +++ b/.github/workflows/pr-handler.yml @@ -0,0 +1,312 @@ +# PR Handler - Comprehensive Pull Request Management +# Handles incoming PRs with intelligent triage, labeling, and status tracking + +name: PR Handler + +on: + pull_request: + types: [opened, edited, synchronize, reopened, ready_for_review] + pull_request_review: + types: [submitted] + issue_comment: + types: [created] + workflow_dispatch: + inputs: + pr_number: + description: 'PR number to handle' + required: false + +permissions: + contents: read + pull-requests: write + issues: write + +jobs: + analyze-pr: + name: Analyze PR + runs-on: ubuntu-latest + if: github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch' + outputs: + is_wip: ${{ steps.analyze.outputs.is_wip }} + pr_type: ${{ steps.analyze.outputs.pr_type }} + needs_review: ${{ steps.analyze.outputs.needs_review }} + can_auto_merge: ${{ steps.analyze.outputs.can_auto_merge }} + org_scope: ${{ steps.analyze.outputs.org_scope }} + + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Analyze PR metadata + id: analyze + uses: actions/github-script@v7 + with: + script: | + const pr = context.payload.pull_request || + await github.rest.pulls.get({ + owner: context.repo.owner, + repo: context.repo.repo, + pull_number: context.payload.inputs?.pr_number || context.issue.number + }).then(r => r.data); + + // Check if WIP + const isWIP = pr.title.includes('[WIP]') || pr.title.includes('WIP:') || pr.draft; + core.setOutput('is_wip', isWIP); + + // Determine PR type based on title and files + let prType = 'other'; + const title = pr.title.toLowerCase(); + if (title.includes('workflow') || title.includes('ci') || title.includes('github actions')) { + prType = 'workflow'; + } else if (title.includes('doc') || title.includes('wiki') || title.includes('readme')) { + prType = 'documentation'; + } else if (title.includes('test') || title.includes('ci/cd')) { + prType = 'testing'; + } else if (title.includes('infrastructure') || title.includes('setup')) { + prType = 'infrastructure'; + } else if (title.includes('agent') || title.includes('ai') || title.includes('claude')) { + prType = 'ai-feature'; + } else if (title.includes('collaboration') || title.includes('memory')) { + prType = 'core-feature'; + } + core.setOutput('pr_type', prType); + + // Determine org scope + const orgPatterns = [ + 'BlackRoad-OS', 'BlackRoad-AI', 'BlackRoad-Cloud', 'BlackRoad-Hardware', + 'BlackRoad-Security', 'BlackRoad-Labs', 'BlackRoad-Foundation', + 'BlackRoad-Media', 'BlackRoad-Studio', 'BlackRoad-Interactive', + 'BlackRoad-Education', 'BlackRoad-Gov', 'BlackRoad-Archive', + 'BlackRoad-Ventures', 'Blackbox-Enterprises' + ]; + const body = pr.body || ''; + const orgsFound = orgPatterns.filter(org => + title.includes(org) || body.includes(org) + ); + core.setOutput('org_scope', orgsFound.join(',') || 'all'); + + // Check if needs review + const needsReview = !isWIP && pr.requested_reviewers.length === 0; + core.setOutput('needs_review', needsReview); + + // Check if can auto-merge (copilot branches with checks passed) + const canAutoMerge = pr.head.ref.startsWith('copilot/') && + !isWIP && + pr.mergeable_state === 'clean'; + core.setOutput('can_auto_merge', canAutoMerge); + + return { + number: pr.number, + isWIP, + prType, + orgScope: orgsFound.join(',') || 'all', + needsReview, + canAutoMerge + }; + + label-pr: + name: Label PR + runs-on: ubuntu-latest + needs: analyze-pr + steps: + - name: Apply labels + uses: actions/github-script@v7 + with: + script: | + const prType = '${{ needs.analyze-pr.outputs.pr_type }}'; + const isWIP = '${{ needs.analyze-pr.outputs.is_wip }}' === 'true'; + const orgScope = '${{ needs.analyze-pr.outputs.org_scope }}'; + + const labels = []; + + // Type labels + const typeLabels = { + 'workflow': 'workflows', + 'documentation': 'documentation', + 'testing': 'testing', + 'infrastructure': 'infrastructure', + 'ai-feature': 'ai-enhancement', + 'core-feature': 'enhancement' + }; + if (typeLabels[prType]) { + labels.push(typeLabels[prType]); + } + + // Status labels + if (isWIP) { + labels.push('work-in-progress'); + } else { + labels.push('ready-for-review'); + } + + // Org scope labels + if (orgScope && orgScope !== 'all') { + const orgs = orgScope.split(','); + if (orgs.length > 3) { + labels.push('multi-org'); + } else { + orgs.forEach(org => { + const code = org.split('-').pop(); + labels.push(`org:${code.toLowerCase()}`); + }); + } + } + + // Apply labels + if (labels.length > 0) { + await github.rest.issues.addLabels({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + labels: labels + }); + } + + comment-on-pr: + name: Comment on PR + runs-on: ubuntu-latest + needs: analyze-pr + if: needs.analyze-pr.outputs.needs_review == 'true' + steps: + - name: Add helpful comment + uses: actions/github-script@v7 + with: + script: | + const prType = '${{ needs.analyze-pr.outputs.pr_type }}'; + const isWIP = '${{ needs.analyze-pr.outputs.is_wip }}' === 'true'; + + let comment = '## ๐Ÿค– PR Handler Analysis\n\n'; + comment += `**Type:** ${prType}\n`; + comment += `**Status:** ${isWIP ? 'Work in Progress' : 'Ready for Review'}\n\n`; + + if (!isWIP) { + comment += '### Next Steps\n'; + comment += '- [ ] Code review by maintainers\n'; + comment += '- [ ] CI checks pass\n'; + comment += '- [ ] Resolve any review comments\n'; + comment += '- [ ] Ready to merge\n\n'; + } + + // Type-specific guidance + const guidance = { + 'workflow': 'โš ๏ธ **Workflow changes** require careful review for security and permissions.', + 'documentation': '๐Ÿ“š **Documentation** - Ensure accuracy and completeness.', + 'testing': '๐Ÿงช **Testing changes** - Verify test coverage and quality.', + 'infrastructure': '๐Ÿ—๏ธ **Infrastructure** - Review for production readiness.', + 'ai-feature': '๐Ÿค– **AI Feature** - Test thoroughly with different scenarios.', + 'core-feature': 'โญ **Core Feature** - Requires comprehensive review and testing.' + }; + + if (guidance[prType]) { + comment += `### โ„น๏ธ ${guidance[prType]}\n\n`; + } + + comment += '---\n'; + comment += '*Automated by BlackRoad PR Handler*'; + + // Check if comment already exists + const comments = await github.rest.issues.listComments({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + }); + + const existing = comments.data.find(c => + c.body.includes('PR Handler Analysis') && + c.user.type === 'Bot' + ); + + if (!existing) { + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body: comment + }); + } + + request-reviewers: + name: Request Reviewers + runs-on: ubuntu-latest + needs: analyze-pr + if: needs.analyze-pr.outputs.needs_review == 'true' && needs.analyze-pr.outputs.is_wip == 'false' + steps: + - name: Assign reviewers + uses: actions/github-script@v7 + with: + script: | + // Request review from repository owner + try { + await github.rest.pulls.requestReviewers({ + owner: context.repo.owner, + repo: context.repo.repo, + pull_number: context.issue.number, + reviewers: ['blackboxprogramming'] + }); + } catch (error) { + console.log('Could not request reviewers:', error.message); + } + + check-merge-readiness: + name: Check Merge Readiness + runs-on: ubuntu-latest + needs: analyze-pr + if: needs.analyze-pr.outputs.can_auto_merge == 'true' + steps: + - name: Check if ready to merge + uses: actions/github-script@v7 + with: + script: | + const pr = context.payload.pull_request; + + // Check CI status + const checks = await github.rest.checks.listForRef({ + owner: context.repo.owner, + repo: context.repo.repo, + ref: pr.head.sha + }); + + const allPassed = checks.data.check_runs.every(check => + check.conclusion === 'success' || check.conclusion === 'skipped' + ); + + if (allPassed && pr.mergeable) { + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: pr.number, + body: 'โœ… **This PR is ready to merge!**\n\nAll checks have passed and the PR is mergeable. A maintainer can merge this PR.' + }); + } + + update-pr-status: + name: Update PR Status + runs-on: ubuntu-latest + needs: [analyze-pr, label-pr, comment-on-pr] + if: always() + steps: + - name: Update status + uses: actions/github-script@v7 + with: + script: | + const prType = '${{ needs.analyze-pr.outputs.pr_type }}'; + const isWIP = '${{ needs.analyze-pr.outputs.is_wip }}' === 'true'; + + console.log('PR Analysis Complete:'); + console.log(' Type:', prType); + console.log(' WIP:', isWIP); + console.log(' Labels:', '${{ needs.label-pr.result }}'); + console.log(' Comment:', '${{ needs.comment-on-pr.result }}'); + + // Update summary + core.summary + .addHeading('PR Handler Summary') + .addTable([ + [{data: 'Property', header: true}, {data: 'Value', header: true}], + ['PR Type', prType], + ['Status', isWIP ? '๐Ÿšง Work in Progress' : 'โœ… Ready for Review'], + ['Labels Applied', '${{ needs.label-pr.result }}'], + ['Comment Added', '${{ needs.comment-on-pr.result }}'] + ]) + .write(); diff --git a/PR_MANAGEMENT.md b/PR_MANAGEMENT.md new file mode 100644 index 0000000..7df11c5 --- /dev/null +++ b/PR_MANAGEMENT.md @@ -0,0 +1,348 @@ +# Pull Request Management + +> **Automated PR handling system for the BlackRoad .github repository** + +--- + +## Overview + +The BlackRoad PR Handler provides automated triage, labeling, and management of pull requests across the organization. It helps maintainers quickly assess and process incoming PRs with intelligent categorization and status tracking. + +--- + +## Current Open PRs + +### High Priority + +#### PR #7: Update MEMORY.md +- **Status**: Ready for review (not draft) +- **Type**: Documentation update +- **Summary**: Marks completed roadmap items through dispatcher +- **Changes**: 1101 additions, 5 deletions, 6 files +- **Action Needed**: Final review and merge + +#### PR #12: Add CLAUDE.md +- **Status**: Draft +- **Type**: Documentation +- **Summary**: AI assistant guide for BlackRoad Bridge +- **Changes**: 340 additions, 1 file +- **Action Needed**: Finalize and mark ready for review + +### Infrastructure & Testing + +#### PR #2: Infrastructure Setup +- **Status**: Ready for review (not draft) +- **Type**: Infrastructure +- **Summary**: Testing, CI/CD, auto-merge, Claude Code API integration +- **Changes**: 7267 additions, 21 deletions, 38 files +- **Scope**: Comprehensive testing framework (97 tests, 73% coverage) +- **Action Needed**: Review and merge - foundational infrastructure + +### Feature Development + +#### PR #3: Wiki Documentation +- **Status**: Draft +- **Type**: Documentation +- **Summary**: Comprehensive Wiki documentation structure (27 pages, 3,522 lines) +- **Changes**: 3853 additions, 30 files +- **Action Needed**: Review wiki structure and publishing plan + +#### PR #4: AI Agent Codespace +- **Status**: Ready for review (not draft) +- **Type**: AI Feature +- **Summary**: Collaborative AI agent codespace with open source models +- **Changes**: 3771 additions, 1 deletion, 23 files +- **Action Needed**: Test agent collaboration features + +#### PR #5: Org Sync System +- **Status**: Ready for review (not draft) [WIP in title] +- **Type**: Infrastructure +- **Summary**: Updates pushing to other orgs and repos +- **Changes**: 1216 additions, 2 deletions, 8 files +- **Action Needed**: Complete security scan + +#### PR #6: Collaboration & Memory +- **Status**: Ready for review (not draft) [WIP in title] +- **Type**: Core Feature +- **Summary**: Collaboration and memory functions for sessions +- **Changes**: 3665 additions, 15 files +- **Action Needed**: Update main Bridge documentation + +### Current PR (This One) + +#### PR #18: Handle Incoming PRs +- **Status**: Work in Progress +- **Type**: Workflow/Automation +- **Summary**: PR handling workflow and management system +- **Action Needed**: Complete implementation + +--- + +## PR Handling Workflow + +### Automatic Processing + +When a PR is opened or updated, the PR Handler workflow automatically: + +1. **Analyzes** the PR + - Detects WIP status + - Categorizes type (workflow, documentation, testing, infrastructure, ai-feature, core-feature) + - Identifies org scope + - Checks merge readiness + +2. **Labels** the PR + - Type labels (workflows, documentation, testing, etc.) + - Status labels (work-in-progress, ready-for-review) + - Org scope labels (org:os, org:ai, multi-org, etc.) + +3. **Comments** on the PR + - Analysis summary + - Next steps checklist + - Type-specific guidance + - Merge readiness status + +4. **Requests Reviews** + - Assigns appropriate reviewers + - Notifies maintainers + +5. **Tracks Status** + - Monitors CI checks + - Updates merge readiness + - Provides status summary + +### PR Types and Handling + +#### ๐Ÿ”ง Workflow PRs +- **Security Focus**: Extra scrutiny for permissions and secrets +- **Testing**: Validate YAML syntax and workflow logic +- **Deployment**: Test in safe environment first + +#### ๐Ÿ“š Documentation PRs +- **Content Review**: Check accuracy and completeness +- **Links**: Verify all links work +- **Style**: Ensure consistent formatting + +#### ๐Ÿงช Testing PRs +- **Coverage**: Verify adequate test coverage +- **Quality**: Check test quality and assertions +- **Integration**: Ensure tests work in CI + +#### ๐Ÿ—๏ธ Infrastructure PRs +- **Production Ready**: Review for production deployment +- **Dependencies**: Check for security vulnerabilities +- **Backwards Compat**: Ensure no breaking changes + +#### ๐Ÿค– AI Feature PRs +- **Testing**: Test with various scenarios +- **Performance**: Check resource usage +- **Integration**: Verify works with existing AI systems + +#### โญ Core Feature PRs +- **Comprehensive Review**: Requires thorough examination +- **Testing**: Extensive test coverage needed +- **Documentation**: Must update docs + +--- + +## PR Review Checklist + +For reviewers, use this checklist when reviewing PRs: + +### All PRs +- [ ] Code quality meets standards +- [ ] Changes are focused and minimal +- [ ] No unintended changes included +- [ ] Commit messages are clear +- [ ] CI checks pass + +### Code Changes +- [ ] Tests added/updated +- [ ] No security vulnerabilities +- [ ] Error handling is appropriate +- [ ] Logging is adequate +- [ ] Performance impact is acceptable + +### Documentation Changes +- [ ] Information is accurate +- [ ] Examples work as shown +- [ ] Links are valid +- [ ] Formatting is consistent + +### Workflow Changes +- [ ] Permissions are minimal +- [ ] Secrets are properly referenced +- [ ] Triggers are appropriate +- [ ] Error handling is robust + +--- + +## Merging Strategy + +### Auto-Merge Eligible +PRs from `copilot/**` branches can auto-merge when: +- Not marked as draft or WIP +- All CI checks pass +- No merge conflicts +- At least one approval (if required) + +### Manual Merge Required +- PRs modifying workflow files +- PRs from external contributors +- Breaking changes +- Major feature additions + +### Merge Methods +- **Squash Merge**: Default for feature branches (preserves clean history) +- **Rebase Merge**: For linear history preservation +- **Merge Commit**: For keeping all commits (rarely used) + +--- + +## Labels + +### Type Labels +- `workflows` - GitHub Actions workflows +- `documentation` - Documentation changes +- `testing` - Test additions/changes +- `infrastructure` - Infrastructure setup +- `ai-enhancement` - AI/ML features +- `enhancement` - Core feature additions +- `bug` - Bug fixes +- `dependencies` - Dependency updates +- `security` - Security fixes + +### Status Labels +- `work-in-progress` - Still being worked on +- `ready-for-review` - Ready for maintainer review +- `needs-changes` - Changes requested +- `approved` - Approved for merge +- `blocked` - Blocked by something + +### Priority Labels +- `priority-high` - Needs immediate attention +- `priority-medium` - Normal priority +- `priority-low` - Can wait + +### Org Scope Labels +- `org:os` - BlackRoad-OS +- `org:ai` - BlackRoad-AI +- `org:cloud` - BlackRoad-Cloud +- `multi-org` - Affects multiple orgs +- `all-orgs` - Affects all organizations + +--- + +## Commands + +### PR Comment Commands + +Maintainers can use these commands in PR comments: + +- `/merge` - Merge the PR (if eligible) +- `/rebase` - Rebase the PR +- `/label