Orchestration Hub

The Problem: Scale Without Legibility

Every system with 116 repositories needs a single place that answers "what exists, what's its status, and who owns it?"^[1] Meadows identifies information flows as the most powerful leverage points in complex systems — when participants can see the system's state, they make better decisions. Most multi-repo systems rely on tribal knowledge: someone remembers which repo does what, which ones are active, which ones were experiments. That breaks at scale. It breaks when you onboard new contributors — human or AI. And it breaks when you need to answer a simple question: is this system healthy?^[2]

The Solution

A machine-readable JSON registry (registry-v2.json) that serves as the single source of truth for the entire eight-organ system.^[3] Fowler's principle of a "Repository" pattern — an abstraction layer that mediates between the domain and data mapping layers — applies here at the organizational scale. Every repository entry carries its current status, documentation tier, dependency declarations, promotion state, implementation status, and portfolio relevance score. The registry isn't documentation about the system — it is the system's self-knowledge. When the registry and reality disagree, either the registry must be updated or reality must be fixed. This is Article I of the system constitution.^[4]

            ┌──────────────────────────────┐
            │   orchestration-start-here    │
            │                              │
            │  registry-v2.json            │
            │  governance-rules.json       │
            │  5 workflows · 3 scripts     │
            └──────────┬───────────────────┘
                       │
          ┌────────────┼────────────────┐
          │            │                │
 ┌────────▼──────┐ ┌──▼──────────┐ ┌───▼──────────┐
 │   ORGAN-I     │ │  ORGAN-II   │ │  ORGAN-III   │
 │   Theory      │─▶  Art        │─▶  Commerce    │
 │   18 repos    │ │  22 repos   │ │  21 repos    │
 └───────────────┘ └─────────────┘ └──────────────┘
          │            │                │
 ┌────────▼──────┐ ┌──▼──────────┐ ┌───▼──────────┐
 │   ORGAN-V     │ │  ORGAN-VI   │ │  ORGAN-VII   │
 │   Process     │ │  Community  │ │  Marketing   │
 └───────────────┘ └─────────────┘ └──────────────┘
                       │
            ┌──────────▼───────────────────┐
            │       meta-organvm           │
            │       (Umbrella Org)         │
            └──────────────────────────────┘

Flow enforced: I → II → III (no back-edges)
Hub validates all 31 dependency edges.

Registry Architecture

The v2 registry is a single JSON file with a versioned envelope wrapping per-organ repository arrays. The top-level structure carries a deployment model declaration, a summary block with system-wide counts, and an audit_history array that the monthly workflow appends to automatically — giving the file a built-in changelog of every health check ever run.^[5] The schema follows the Composite pattern — each repository is a leaf node, organs are composites, and the registry root allows queries at any granularity without traversing the entire structure.

{
  "version": "2.0",
  "schema_version": "0.2",
  "deployment_model": "PARALLEL_ALL_ORGANS",
  "summary": {
    "total_repos": 80,
    "operational_organs": 8,
    "portfolio_strength": "SILVER (ALL ORGANS)"
  },
  "organs": {
    "ORGAN-I": {
      "name": "Theory",
      "launch_status": "OPERATIONAL",
      "repositories": [ ... ]
    }
  },
  "audit_history": [
    { "date": "2026-02-01", "total_repos": 79, "violations": 0 },
    { "date": "2026-03-01", "total_repos": 80, "violations": 0 }
  ]
}

Each of the 116 entries in the registry carries structured metadata that enables both automated validation and human reasoning about system state. ORGAN-III repositories carry two additional fields — type (SaaS / B2B / B2C / internal) and revenue — reflecting that commerce-layer repos have a business model dimension absent from theoretical or artistic work.

{
  "orchestration-start-here": {
    "organ": "IV",
    "status": "ACTIVE",
    "tier": "flagship",
    "promotion_status": "GRADUATED",
    "implementation_status": "PRODUCTION",
    "documentation_status": "FLAGSHIP README DEPLOYED",
    "dependencies": [],
    "portfolio_relevance": "CRITICAL",
    "ci_workflow": "ci-python.yml",
    "platinum_status": true,
    "last_validated": "2026-03-01T02:00:00Z",
    "description": "Central nervous system of the eight-organ architecture"
  }
}

Because the registry is plain JSON, any tool in the standard Unix toolchain can query it without a bespoke client. The three commands below cover the most common operational queries:

# Count repos per organ
jq '.organs | to_entries[] | {organ: .key, count: (.value.repositories | length)}' registry.json

# Find all repos with CRITICAL portfolio relevance
jq '[.organs[].repositories[] | select(.portfolio_relevance == "CRITICAL")] | .[].name' registry.json

# Find undocumented active repos (candidates for the monthly audit warning list)
jq '[.organs[].repositories[]
  | select(.documentation_status != "DEPLOYED"
    and .documentation_status != "FLAGSHIP README DEPLOYED"
    and .documentation_status != "INFRASTRUCTURE"
    and .status == "ACTIVE")] | .[].name' registry.json

Validation Pipeline

The validation pipeline runs on every pull request that touches a dependency manifest in any organ repository. It fetches the central registry and governance rules from this hub, classifies the pull request's source organ, then runs three sequential checks before allowing a merge.^[6] Humble and Farley's core argument — that the deployment pipeline should be the only legitimate path for changing system state — applies at the governance layer: no dependency may be added except through a PR that passes all three checks.

Direction validation enforces the I→II→III flow: ORGAN-I has no upstream dependencies, ORGAN-VII depends exclusively on ORGAN-V, and every other organ's allowed dependency set is defined in governance-rules.json. Circular dependency detection builds the full system-wide graph — not just the PR under review — and runs DFS cycle detection so that a cycle introduced transitively is still caught. Transitive depth analysis measures the longest chain from the PR's repo through all dependencies; the limit of four leaves one additional layer of growth before requiring architectural review.

def validate_dependencies(registry: dict) -> list[str]:
    """Validate all dependency edges. Returns list of violations."""
    violations = []
    organ_order = {'I': 1, 'II': 2, 'III': 3, 'IV': 4,
                   'V': 5, 'VI': 6, 'VII': 7, 'META': 8}

    for repo, meta in registry.items():
        src_organ = meta['organ']
        for dep in meta.get('dependencies', []):
            dst_organ = dep.split('/')[0].split('-')[-1].upper()
            if organ_order.get(dst_organ, 0) < organ_order.get(src_organ, 0):
                violations.append(f"BACK-EDGE: {repo} -> {dep}")

    # Cycle detection via topological sort
    if has_cycle(build_graph(registry)):
        violations.append("CIRCULAR DEPENDENCY DETECTED")

    return violations  # Must be empty for merge gate to pass

Governance as Code

The governance model is codified in governance-rules.json — a machine-readable constitution with six articles and four amendments.^[7] Scott's critique of "high modernist" schemes warns against legibility imposed without local knowledge — these governance rules encode both top-down constraints (no back-edges, mandatory documentation) and bottom-up flexibility (promotion is earned, not assigned). The most important constraint: no back-edges in the dependency graph. Theory feeds art feeds commerce (I→II→III), validated automatically across all 31 dependency edges.^[8]

The four amendments handle edge cases the six articles cannot cover with clean automation. Amendment A establishes the Bronze Tier Launch Path — five rigorously documented repos beat forty-four mediocre ones — encoding a quality-over-quantity policy directly in the governance file. Amendment D acknowledges AI non-determinism: all AI-generated deliverables require human review before a repo may advance beyond CANDIDATE state, preventing automated systems from self-promoting their own output.

Automation: Five Workflows, Three Scripts

The automation layer transforms governance from aspiration to enforcement. All five workflows are data-driven: logic lives in registry-v2.json and governance-rules.json, not in workflow YAML. Changing a governance rule — for example, permitting a new dependency direction — requires updating the JSON constitution; no workflow file needs modification. The three Python scripts share the same zero-external-dependencies constraint (Python 3.12 standard library only), making them portable across any environment with a Python interpreter.^[9]

• validate-dependencies — Checks the dependency graph on every PR that touches a dependency manifest. Cycle detection, transitive depth analysis (limit: 4), back-edge blocking. Posts a structured PR comment with per-check results.
• monthly-organ-audit — Full system health check on the 1st of each month. Runs all three Python scripts, opens a GitHub Issue with the Markdown report and metrics table, then commits an updated audit_history entry back to registry.json.
• promote-repo — Handles promotion state machine transitions triggered by issue comment commands. Pre-validates against governance rules; for commerce promotions, verifies revenue model documentation. Executes repository creation in the destination organ when ORCHESTRATION_PAT is configured.
• publish-process — Extracts source README content and generates a structured ORGAN-V process essay with YAML frontmatter, then opens a PR in organvm-v-logos/public-process. Connects the Theory→Art→Commerce pipeline with the public documentation organ.
• distribute-content — POSSE distribution to Mastodon (HTTP 200 verified) and Discord (HTTP 204 verified). Triggered by the ready-to-distribute label on any issue in this repository.

# Run dependency direction validation (exit 0 = clean, exit 1 = violation)
python3 scripts/validate-deps.py \
  --registry registry.json \
  --governance governance-rules.json

# Full organ audit — produces structured Markdown report
python3 scripts/organ-audit.py \
  --registry registry.json \
  --governance governance-rules.json \
  --output audit-report.md

# Calculate system-wide metrics → metrics.json
python3 scripts/calculate-metrics.py \
  --registry registry.json \
  --output metrics.json

# Trigger monthly audit manually via GitHub CLI
gh workflow run monthly-organ-audit.yml \
  --repo organvm-iv-taxis/orchestration-start-here

# Trigger dependency validation manually
gh workflow run validate-dependencies.yml \
  --repo organvm-iv-taxis/orchestration-start-here

The calculate-metrics.py script produces a metrics.json snapshot that the monthly audit workflow embeds in its GitHub Issue report. Each run appends to the registry's audit_history array, giving every audit a persistent record without requiring a separate data store. The system is self-archiving by design.

Why a Registry Matters

A machine-readable registry enables automation (CI/CD workflows query it), auditing (monthly health checks generate reports from it), and honest portfolio presentation (the portfolio site reads from the same source of truth as the governance scripts).^[10] Deming's principle — "In God we trust; all others must bring data" — is enacted literally: the registry is the data. It's what makes the eight-organ system governable rather than merely large. It's the difference between 116 repositories and a system.^[11]

Tradeoffs & Lessons

• Single file vs. distributed config — Keeping the entire registry in one JSON file means every change touches one file and every query is a local read. The alternative (per-repo config files aggregated at build time) would be more distributed but harder to validate atomically. At 116 entries the single-file approach works; at 500 it might not.^[12]
• Strict governance vs. velocity — The no-back-edges rule and promotion state machine add friction to every cross-organ change. This is intentional: the friction prevents the most common failure mode of multi-repo systems (tangled dependencies that nobody can reason about). But it slows rapid prototyping across organ boundaries.
• Monthly audit cadence — Monthly is frequent enough to catch drift but infrequent enough to be actionable. Weekly would create audit fatigue; quarterly would let too much drift accumulate. The auto-commit of audit results into registry.json keeps the cadence self-enforcing.
• Constitution as code — Writing governance rules as JSON rather than prose forces precision but loses nuance. Article V ("Portfolio-Quality Documentation") requires human judgment that cannot be reduced to a JSON field. The compromise: automated checks for measurable criteria, manual review gates for qualitative ones.^[13]
• Zero external dependencies in scripts — All three Python scripts use only the standard library. This keeps them executable in any GitHub Actions runner without a pip install step and eliminates an entire class of supply-chain failure modes. The tradeoff is verbosity: graph algorithms that networkx would express in two lines require explicit DFS implementations.