Add BlackRoad OS technical framework and fix self-healing workflow cascade

[Copilot]

The architecture docs lacked the full technical framework (org matrix, domain registry, deca-layered scaffold, Pi cluster specs, routing matrix, CLI layers). Separately, self-healing-master.yml and test-auto-heal.yml used workflows: ["*"] which triggered on their own completion, creating an infinite cascade of 600+ failure issues. The blackroad-agent.yml required [self-hosted, pi] runners unavailable in CI.

CI workflow fixes

• blackroad-agent.yml: runs-on: [self-hosted, pi] → runs-on: ubuntu-latest — Pi runners don't exist in GitHub-hosted CI
• self-healing-master.yml / test-auto-heal.yml: Replace workflows: ["*"] with explicit workflow list to break the self-triggering loop:

# Before — triggers on itself, infinite cascade
workflow_run:
  workflows: ["*"]

# After — only monitors actual workloads
workflow_run:
  workflows:
    - "🚀 Auto Deploy"
    - "🔒 Security Scan"
    - "🤖 BlackRoad Shared Agent CI"

Architecture documentation (BLACKROAD_ARCHITECTURE.md)

• 15-org enterprise matrix with responsibilities and example repos
• 18-domain registry with Cloudflare integration mapping
• @blackroad-agents deca-layered scaffold (10 steps: review → org → team → project → agent → repo → device → drive → cloudflare → website editor)
• Pi 5 cluster hardware specs and GH_COPILOT_OVERRIDE_PROXY_URL LiteLLM proxy config
• CLI v3 layer definitions (L3–L8), @BlackRoadBot routing matrix, roadchain witnessing, rate limit mitigation table

Agent config (agent.json)

• Added scaffold, organizations, cli_layers, and copilot_proxy fields to formalize the orchestration topology

Original prompt

Distributed Multi-Agent Orchestration and Autonomous Infrastructure: The BlackRoad OS Technical Framework
The paradigm of modern software engineering is increasingly characterized by the transition from static, human-operated development environments to dynamic, agentic ecosystems. The BlackRoad OS framework represents an advanced implementation of this shift, integrating a multi-layered command-line interface, a decentralized memory core known as Lucidia, and a witnessing ledger system titled roadchain. Central to this architecture is the deployment of autonomous routing matrices—specifically @BlackRoadBot and @blackroad-agents—which facilitate the distribution of high-level intent across a vast array of cloud platforms, local hardware clusters, and organizational structures. This report provides an exhaustive technical analysis of the BlackRoad architecture, detailing the mechanisms of its deca-layered task scaffold, the technical requirements for local inference offloading via Raspberry Pi clusters, and the theoretical underpinnings that inform its design.
The GitHub Enterprise Organizational Matrix
The operational surface area of BlackRoad OS is structured within a GitHub Enterprise environment, specifically hosted at https://github.com/enterprises/blackroad-os. This enterprise-level abstraction provides the necessary governance and security boundaries for managing a hierarchy of fifteen distinct organizations. Each organization is tasked with a specific functional domain, ranging from core kernel development to hardware management and educational outreach. The distribution of tasks across these organizations is not merely a logistical necessity but a strategic implementation of the principle of least privilege, ensuring that agents operating within one domain—such as BlackRoad-Security—are isolated from sensitive assets in another, such as BlackRoad-Ventures.
Organization Domains and Architectural Alignment
The fifteen organizations within the BlackRoad ecosystem serve as the primary targets for the @blackroad-agents task distribution layer. These organizations are meticulously categorized to ensure that @BlackRoadBot can route requests with high precision based on the context of the GitHub comment.
Organization Name
Primary Responsibility
Repository Examples
Blackbox-Enterprises
Corporate and Enterprise Integrations
blackbox-api, enterprise-bridge
BlackRoad-AI
Core LLM and Reasoning Engine Development
lucidia-core, blackroad-reasoning
BlackRoad-Archive
Long-term Data Persistence and Documentation
blackroad-os-docs, history-ledger
BlackRoad-Cloud
Infrastructure as Code and Orchestration
cloud-orchestrator, railway-deploy
BlackRoad-Education
Onboarding and Documentation Frameworks
br-help, onboarding-portal
BlackRoad-Foundation
Governance and Protocol Standards
protocol-specs, governance-rules
BlackRoad-Gov
Regulatory Compliance and Policy Enforcement
compliance-audit, regulatory-tools
BlackRoad-Hardware
SBC and IoT Device Management
blackroad-agent-os, pi-firmware
BlackRoad-Interactive
User Interface and Frontend Systems
blackroad-os-web, interactive-ui
BlackRoad-Labs
Experimental R&D and Prototyping
experimental-agents, quantum-lab
BlackRoad-Media
Content Delivery and Public Relations
media-engine, pr-automation
BlackRoad-OS
Core System Kernel and CLI Development
blackroad-cli, kernel-source
BlackRoad-Security
Auditing, Cryptography, and Security
security-audit, hash-witnessing
BlackRoad-Studio
Production Assets and Creative Tooling
lucidia-studio, creative-assets
BlackRoad-Ventures
Strategic Growth and Ecosystem Funding
tokenomics-api, venture-cap

The management of these fifteen organizations requires an automated approach to permissioning. The implementation utilizes GitHub Apps for cross-organization repository access, which is considered superior to Personal Access Tokens (PATs) due to their short-lived, granular permissions and ability to act on behalf of an organization rather than an individual user. This is particularly critical given the expiration of granular access tokens observed in system logs, such as the blackroad-npm-token.
Infrastructure and Domain Registry
The BlackRoad OS infrastructure utilizes a hybrid model that spans global cloud providers and local compute clusters. This distribution allows the system to balance the high-availability requirements of public-facing services with the data sovereignty and cost-efficiency needs of agentic inference.
Domain Architecture and Cloudflare Integration
The project manages an extensive registry of eighteen primary domains, all of which are orchestrated via Cloudflare. This domain layer serves as the ingress point for the @BlackRoadBot routing matrix. Cloudflare Tunnels are employed to securely expose local Raspberry Pi nodes to the public internet, allowing the bot to invoke local inference models without exposing internal network ports.
Domain Name
Intended Functional Use Case
Associated Organization
blackboxprogramming.io
Developer Ed...

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Pull request overview

Expands BlackRoad OS architecture documentation with a more complete technical framework (org matrix, domain registry, scaffold, CLI layers, Pi cluster inference) and hardens CI workflows to prevent self-triggering workflow_run cascades while restoring compatibility with GitHub-hosted runners.

Changes:

• Documented the BlackRoad OS technical framework (Pi inference/offload, org matrix, domains, scaffold, CLI layers, routing/witnessing).
• Replaced workflow_run.workflows: ["*"] with an explicit workflow allowlist to stop infinite workflow cascades.
• Updated blackroad-agent.yml to use ubuntu-latest instead of unavailable self-hosted Pi runners.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
BLACKROAD_ARCHITECTURE.md	Adds expanded architecture/ops framework sections (Pi inference, org/domain registry, scaffold, CLI layers).
profile/BLACKROAD_ARCHITECTURE.md	Mirrors the expanded architecture documentation for the profile copy.
agent.json	Extends agent identity/config with scaffold, org list, CLI layers, and proxy fields.
.github/workflows/test-auto-heal.yml	Restricts workflow_run triggers to a safe allowlist to prevent self-triggering cascades.
.github/workflows/self-healing-master.yml	Same allowlist restriction for the master healing workflow to stop recursive triggering.
.github/workflows/blackroad-agent.yml	Switches runner to ubuntu-latest for GitHub-hosted CI compatibility.

---

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