Infrastructure setup: testing, CI/CD, auto-merge, and Claude Code API integration

[Copilot]

Establishes production-ready infrastructure for the BlackRoad .github repository: comprehensive testing framework, automated workflows, and developer tooling.

Testing Infrastructure

• 97 tests across Operator (73) and Control Plane (24) with 73% coverage
• pytest configuration with markers, fixtures, and parallel execution
• GitHub Actions CI workflow with multi-version Python testing (3.11, 3.12)
• Coverage reporting (HTML, XML, terminal) with Codecov integration

# tests/operator/test_router.py
def test_route_cloudflare_query(operator):
    result = operator.route("Deploy Cloudflare Worker")
    assert result.org == "BlackRoad-Cloud"
    assert result.confidence > 0.8

# tests/control_plane/test_bridge.py  
def test_bridge_singleton():
    bridge1 = get_bridge()
    bridge2 = get_bridge()
    assert bridge1 is bridge2

Auto-Merge Workflow

Automatic PR merging for copilot/** branches when checks pass:

• Eligibility checking (conflicts, draft status, check results)
• Squash merge strategy
• PR status comments
• Manual override via auto-merge label

Repository Setup

GitHub community health files and automation:

• Issue templates: bug report, feature request, org setup (YAML forms)
• PR template with org routing dropdown
• CODEOWNERS covering 15 organizations
• Dependabot for GitHub Actions and Python dependencies
• Community files: CODE_OF_CONDUCT, CONTRIBUTING, SECURITY, SUPPORT

Claude Code API Documentation

CLAUDE_CODE_API.md with integration patterns:

• Model selection (Claude 4, Claude 3.5 Sonnet/Haiku)
• Cost tracking and budget management
• Error handling with exponential backoff
• BlackRoad-specific patterns (AI Router, Operator, MCP Server)

Control Plane Fixes

Bridge API corrections for prototype integration:

• browse() - Uses Explorer.tree() instead of non-existent show()
• signal() - Returns formatted string (📡 OS → target : message)
• search() - Returns dict results directly from Explorer

All workflows operational. Tests pass locally and in CI.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f6c9bcbfbd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Include path data in Bridge.search results

Bridge.search now returns the raw Explorer.search dicts unchanged, but those dicts only contain type, org, name, and match (see Explorer.search), while the CLI formats results using r['path'] in both cmd_search and interactive search. With this change, any non-empty search result causes a KeyError: 'path', so control_plane.cli search <query> will crash whenever there’s at least one match. Either map the results to include a path field (e.g., from name) or update the CLI to use an existing key. (See control_plane/cli.py lines 123-143 and 186-190 for the path access.)

Useful? React with 👍 / 👎.

[Copilot]

Pull request overview

This PR establishes comprehensive production-ready infrastructure for the BlackRoad .github repository, including testing framework, CI/CD automation, auto-merge workflows, and Claude Code API integration documentation.

Changes:

• Added 97 tests with 73% coverage across Operator (73 tests) and Control Plane (24 tests) prototypes
• Implemented GitHub Actions CI/CD with automated testing, code quality checks, and auto-merge for copilot branches
• Created complete community health files (CODE_OF_CONDUCT, CONTRIBUTING, SECURITY, SUPPORT) following GitHub best practices
• Added comprehensive documentation for testing (TESTING.md), auto-merge (AUTO_MERGE.md), and Claude Code API integration (CLAUDE_CODE_API.md)
• Fixed Control Plane Bridge API methods to match actual prototype implementations
• Configured Dependabot for automated dependency updates and CODEOWNERS for code review assignments

Reviewed changes

Copilot reviewed 37 out of 38 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
tests/operator/test_*.py	Comprehensive test coverage for Operator routing, parsing, and classification
tests/control_plane/test_bridge.py	Tests for unified Bridge CLI interface and lazy loading
tests/conftest.py	Shared pytest fixtures and test configuration
pytest.ini	Pytest configuration with markers, coverage, and test organization
requirements-test.txt	Testing dependencies including pytest, coverage tools, and code quality checkers
.github/workflows/tests.yml	CI workflow with multi-version Python testing and coverage reporting
.github/workflows/auto-merge.yml	Automated PR merging for copilot branches when checks pass
.github/dependabot.yml	Automated dependency update configuration for Actions and Python packages
.github/CODEOWNERS	Code review assignment rules for different repository areas
.github/ISSUE_TEMPLATE/*.yml	Structured issue forms for bugs, features, and org setup
.github/PULL_REQUEST_TEMPLATE.md	PR template with organization routing and testing checklist
prototypes/control-plane/control_plane/bridge.py	Fixed browse(), signal(), and search() methods to match implementations
TESTING.md	Comprehensive testing guide with examples and best practices
AUTO_MERGE.md	Complete auto-merge workflow documentation
CLAUDE_CODE_API.md	Claude Code API integration patterns and best practices
CODE_OF_CONDUCT.md	Contributor Covenant 2.1 code of conduct
CONTRIBUTING.md	Detailed contribution guidelines with AI-assisted development section
SECURITY.md	Security vulnerability reporting and best practices
SUPPORT.md	Support resources and FAQ
README.md	Main repository landing page with quick start guide
CHANGELOG.md	Version history and release notes
CONTRIBUTORS.md	Contributor recognition framework
.gitignore	Comprehensive ignore patterns for Python, testing, and secrets
coverage.xml	Generated coverage report (should not be committed)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

In general, the fix is to explicitly set minimal GITHUB_TOKEN permissions either at the workflow root (applying to all jobs) or per-job, instead of relying on repository defaults. For this workflow, both test and lint jobs only need to read the repository contents; they don’t modify code, issues, or pull requests.

The best fix without changing functionality is to add a top-level permissions block right under name: Tests that sets contents: read. This will apply to both test and lint jobs since neither defines its own permissions. No other scopes (such as pull-requests, issues, or id-token) are needed for the actions currently used (actions/checkout, actions/setup-python, codecov/codecov-action, actions/upload-artifact). No imports or additional methods are required since this is YAML configuration only.

Concretely, edit .github/workflows/tests.yml to insert:

name: Tests
permissions:
  contents: read

leaving the rest of the file unchanged.

In general, the fix is to explicitly restrict the GITHUB_TOKEN permissions used by this workflow to the minimum required, instead of relying on inherited defaults. Because both test and lint jobs only need to read the repository contents and use third-party actions (checkout, setup-python, upload-artifact, codecov), the minimal sensible permissions are contents: read. The simplest, non-functional-change fix is to add a top-level permissions block that applies to all jobs in the workflow.

Concretely, edit .github/workflows/tests.yml and insert a top-level permissions section after the name: Tests line (or anywhere at the root level before jobs:). Set contents: read there. This will apply to both test and lint jobs, and no additional imports or code changes are necessary.

[Copilot]

Pull request overview

Copilot reviewed 37 out of 38 changed files in this pull request and generated 11 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

This snippet uses python -m operator.cli ..., but there is no operator package here (and it conflicts with Python’s stdlib operator). Update the command to the actual Operator CLI module path so the "How do I run the Operator?" answer is runnable.

Suggested change

	python -m operator.cli "your query here"
	python -m prototypes.operator.cli "your query here"

[Copilot]

The assertion assert bridge._operator is not None or bridge._operator is None is a tautology, so this test will always pass even if lazy-loading regresses. Consider asserting a real post-condition (e.g., that accessing bridge.operator returns either an Operator instance when import succeeds, or None when you explicitly simulate an ImportError), and/or assert that _operator changes from None when the dependency is available.

[Copilot]

The assertion assert bridge._metrics is not None or bridge._metrics is None is always true, so it doesn't validate lazy-loading behavior. Replace it with a concrete expectation (e.g., assert bridge.metrics is an instance of Counter when imports work, and add a separate test that forces an ImportError and expects None).

[Copilot]

The assertion assert bridge._explorer is not None or bridge._explorer is None is a tautology and doesn't test anything. Update this to assert a meaningful post-condition of accessing bridge.explorer (instance when available, None when import fails via monkeypatch).

[Copilot]

pr.mergeable can be null while GitHub is still computing mergeability. Treating null as eligible can enable auto-merge for PRs that later resolve to having conflicts. Consider handling the null case explicitly (e.g., retry/poll briefly, or use mergeable_state and require a known-good state) before declaring eligibility.

Suggested change

	if (pr.mergeable === false) {
	eligible = false;
	reasons.push('PR has merge conflicts');
	let mergeable = pr.mergeable;
	// GitHub may report `mergeable` as null while it is still computing mergeability.
	// Poll a few times to get a definitive value before deciding eligibility.
	if (mergeable === null) {
	let attempts = 0;
	const maxAttempts = 3;
	const delayMs = 2000;
	while (mergeable === null && attempts < maxAttempts) {
	await new Promise(resolve => setTimeout(resolve, delayMs));
	const { data: refreshedPr } = await github.rest.pulls.get({
	owner: context.repo.owner,
	repo: context.repo.repo,
	pull_number: pr.number
	});
	mergeable = refreshedPr.mergeable;
	attempts += 1;
	}
	}
	if (mergeable === false || mergeable === null) {
	eligible = false;
	reasons.push('PR has merge conflicts or mergeability is unknown');

[Copilot]

In [coverage:report] exclude_lines, the pattern if __name__ == .__main__.: looks malformed (it won't match the common if __name__ == "__main__": guard). Update this regex so coverage exclusions behave as intended.

[Copilot]

The quick start command uses python -m operator.cli ..., but there is no operator package in this repo (and it will collide with Python’s stdlib operator). From prototypes/operator/, the CLI module appears to be routing/cli.py, so the invocation should be updated accordingly (and similarly for other docs).

Suggested change

	python -m operator.cli "What is the weather?"
	python -m routing.cli "What is the weather?"

[Copilot]

The PR comment body uses context.payload.pull_request?.head?.ref, which is undefined for workflow_run and workflow_dispatch events. This will post unknown/branch even when auto-merge was enabled successfully; use the pr.head.ref you already fetched in this step instead.

Suggested change

	- Branch: \`${context.payload.pull_request?.head?.ref || 'unknown'}\`
	- Merge method: Squash and merge
	- Triggered by: ${context.eventName}
	_This is an automated action by the BlackRoad auto-merge system._
	📡 \`auto-merge → ${context.payload.pull_request?.head?.ref || 'branch'} : enabled\``
	- Branch: \`${pr.head.ref}\`
	- Merge method: Squash and merge
	- Triggered by: ${context.eventName}
	_This is an automated action by the BlackRoad auto-merge system._
	📡 \`auto-merge → ${pr.head.ref} : enabled\``

[Copilot]

The "Test Summary" step reruns the entire test suite (python -m pytest tests/) after it already ran in the previous step, which roughly doubles CI time. Consider instead capturing results from the original run (or outputting pytest --last-failed / pytest --co), or remove the rerun and just echo key artifacts like the coverage summary.

Suggested change

	python -m pytest tests/ --quiet --tb=no || true
	echo "Tests were executed in the 'Run pytest' step above." >> $GITHUB_STEP_SUMMARY
	echo "Coverage XML: coverage.xml (used by Codecov on Python 3.12)." >> $GITHUB_STEP_SUMMARY
	echo "HTML coverage report: htmlcov/ (archived as an artifact on Python 3.12)." >> $GITHUB_STEP_SUMMARY

[Copilot]

This example import from operator.core import Operator appears incorrect (there is no operator.core module here, and operator collides with the stdlib module). Use the actual package/module that defines Operator (e.g., the routing package) so copy/paste works.