Orchestration Hub

The Problem: Scale Without Legibility

The Solution

            ┌──────────────────────────────┐
            │   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

{
  "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 171 entries in the registryA centralized, queryable data store that serves as the single source of truth for all entities and their relationships in a system 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 registryA centralized, queryable data store that serves as the single source of truth for all entities and their relationships in a system 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

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 ingovernance-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 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 whenORCHESTRATION_PAT is configured.
• publish-process — Extracts source README content and generates a structured ORGAN-V process essay with YAML frontmatter, then opens a PR inorganvm-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 registryA centralized, queryable data store that serves as the single source of truth for all entities and their relationships in a system'saudit_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

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 171 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 apip 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.