feat(org): establish the canonical repository registry and relationship source of truth

[szmyty]

Important

Ownership reconciliation needed — 2026-09-25. The location proposed below conflicts with the accepted local ADR-001 and Hygiene ADR-0001: Hygiene owns ecosystem architecture and the repository catalog. Hygiene #60 owns the pending canonical organization-roadmap contract.

Preserve the useful registry/relationship requirements, then reconcile them as extensions or consumers of existing canonical sources. Do not implement a competing canonical registry in .github without a reviewed architectural decision moving ownership. The original proposal below is retained for review; its newer date does not supersede accepted architecture.

The bounded coordination checkpoint is proposed in organization PR #43; this note neither implements nor closes this issue.

Summary

Establish a small, human-maintained organization registry in egohygiene/.github that defines the intended Ego Hygiene repository landscape and cross-repository relationships.

This becomes the canonical organization-level intent layer consumed by Organization Intelligence, Relay aggregation, Observatory, Pace, and architecture tooling.

It should not contain high-frequency generated health or CI state.

Context

The organization is moving toward a hub-and-spoke model:

repository manifests + repository snapshots
        ↓
organization aggregation
        ↓
observatory
        ↓
pace remediation later

The .github repository is the natural organization-level home for durable organizational intent because it already owns organization profile/defaults/templates and existing Organization Intelligence work.

This issue should complement, not duplicate, the existing Organization Intelligence epic and acceptance work.

Proposed Organization Surface

Prefer a structure similar to:

org/
├── ARCHITECTURE.md
├── ROADMAP.md
├── registry.yml
└── relationships.yml

Reuse existing organization documents if they already live elsewhere in this repository rather than creating duplicates.

registry.yml

Define one stable entry per repository.

Suggested fields:

• repository identifier
• GitHub repository name
• organization namespace
• repository type/profile
• lifecycle state
• short purpose
• public/private visibility intent where useful
• product/system ownership
• public site
• documentation
• Aether profile
• whether Relay Repository Intelligence is expected
• whether Observatory should ingest it
• whether Pace should manage convergence
• aliases or predecessor repositories
• explicit notes/exceptions

Keep the registry concise. Detailed repository purpose belongs in the repository's own architecture documents and manifest.

relationships.yml

Capture declared organization relationships such as:

• depends-on
• consumes
• provides
• integrates-with
• generated-by
• governed-by
• validated-by
• synchronized-by
• observed-by
• belongs-to
• shares-infrastructure-with

Relationship entries should use stable repository/system identifiers rather than free-form names.

Do not infer relationships from source code in this file. This is an intentional organization-level declaration.

Generated-State Boundary

Document a clear boundary between:

Default branch

Human-maintained organization truth:

• registry
• relationships
• architecture
• roadmap
• templates and policy

Generated state

High-frequency outputs such as:

• repository snapshots
• health reports
• workflow evidence
• organization snapshots
• generated context summaries

Generated state should not churn the canonical organization-history branch unnecessarily.

A future or existing implementation may use:

• a dedicated state branch
• release artifacts
• Pages artifacts
• another documented generated-data surface

This issue should define the boundary and interface, not build the entire aggregator.

Integration Direction

The registry should be consumable by:

• Relay organization aggregation
• Observatory
• Pace
• organization architecture tooling
• AI agents needing bounded cross-repository context

Repositories should not need to scan the entire organization independently.

Validation

Add deterministic checks for:

• unique repository IDs
• valid lowercase names
• duplicate GitHub repository mappings
• invalid relationship endpoints
• unknown relationship types
• duplicate relationships
• self-dependencies where prohibited
• missing required lifecycle/type fields
• references to retired repositories without explicit lifecycle status

Where practical, compare registered GitHub repositories to the accessible organization inventory and report:

• registered repository missing from GitHub
• GitHub repository absent from registry
• archived repository still marked active

Do not automatically rewrite the registry from discovery.

Acceptance Criteria

• A canonical organization repository registry exists.
• A canonical relationship declaration exists.
• Stable identifiers and lifecycle states are defined.
• Registry entries remain concise and link back to repository-local sources of truth.
• Relationship types are explicit and validated.
• Generated state is explicitly separated from hand-maintained organization intent.
• Validation catches duplicate IDs and dangling relationship endpoints.
• The model is compatible with Relay, Observatory, and Pace.
• Existing Organization Intelligence work consumes or can consume this source without parallel competing registries.
• Documentation explains how a new repository is registered and retired.
• No high-frequency CI state is committed to the default branch by this issue.

Related Work

This should feed the existing Organization Intelligence/control-plane roadmap rather than replace it.