Support organization-scoped convergence for downstream consumer fleets

[szmyty]

Outcome

Generalize Pace's desired-state and convergence model so the same released reconciler can operate on multiple independently owned consumer organizations rather than assuming one Ego Hygiene fleet.

Ego Hygiene remains the reference/dogfood fleet. Incompris LLC will provide the first private second-organization adoption proof.

Architecture

consumer organization profile
        +
platform distribution lock
        +
consumer repository catalog
        +
current repository locks/evidence
        ↓
Pace plan
        ↓
organization-scoped drift graph
        ↓
reviewed repository-sized proposals
        ↓
verify exact candidate → open bounded PR

Pace converges. It does not become the source of organization policy, repository content, or platform implementation.

Current gap

The existing lock and fleet-convergence design is strong, but its documented inputs and examples are centered on the Hygiene catalog and Ego Hygiene fleet. A downstream organization needs the same safety model with its own catalog, desired capabilities, exceptions, private repositories, and adoption cadence.

Required behavior

Organization namespace

Every plan, lock, proposal, snapshot reference, and diagnostic must carry a stable organization identity and represented organization-profile revision.

• Never infer organization identity from a local folder name.
• Do not merge repositories from separate organizations into one mutation scope implicitly.
• Repository identity must remain unambiguous when different organizations use the same repository name.
• Cross-organization portfolio views may exist elsewhere, but Pace mutation authority remains organization scoped.

Portable desired state

Consume the contracts from egohygiene/hygiene#42 and egohygiene/holon#41:

• consumer-owned organization profile;
• immutable platform distribution lock;
• repository catalog/manifests;
• Holon materialization receipts or candidate plans where applicable;
• current Pace locks;
• Observatory evidence matched to the same organization/repository/revision.

No Pace rule may require the consumer organization to be named egohygiene.

Distribution upgrades

Support a reviewed organization-level distribution upgrade that:

1. compares the current and proposed compatibility sets;
2. resolves which repositories are affected;
3. distinguishes required, optional, blocked, exempt, not-applicable, and already-current repositories;
4. emits dependency-ordered repository-sized plans;
5. preserves repository-specific exceptions and consumer-owned files;
6. verifies exact candidate trees before PR proposal;
7. records rollback to the previous organization/repository lock.

One organization-wide version change must not become one giant cross-repository PR transaction.

Private consumer safety

• Private repository inventory, paths, issue content, and evidence stay in private/local state unless explicitly projected elsewhere.
• Public Ego Hygiene fixtures must use synthetic external organizations.
• A downstream organization can run the reconciler locally without publishing its fleet catalog.
• Credentials remain runtime inputs; they are never serialized into plans or locks.

Required proofs

• Ego Hygiene current fleet remains supported.
• A synthetic external organization with overlapping repository names produces isolated state.
• A private Incompris canary can plan and propose one bounded repository upgrade from a pinned Ego Hygiene platform distribution.
• A failed/stale/partial consumer fleet does not contaminate another organization's plan.

Acceptance criteria

• Pace schemas carry stable organization identity and represented organization-profile revision.
• Generic convergence accepts any valid Hygiene #42 consumer profile rather than a hard-coded Ego Hygiene catalog.
• Repository identity is collision-safe across organizations.
• Desired-state locks preserve immutable platform distribution and producer references.
• Distribution upgrades produce deterministic dependency-ordered repository-sized plans.
• Existing repository exceptions and consumer-owned content are preserved.
• Private organization metadata is not emitted into public/default artifacts.
• Cross-organization mutation is impossible without an explicit separately reviewed scope.
• Ego Hygiene passes as the dogfood fleet.
• A synthetic external fleet passes from a clean checkout.
• A private Incompris canary demonstrates plan → review → candidate verification → PR proposal without copying implementation source.
• Rollback/recovery returns each repository to its prior represented lock when safe.

Dependencies / related

• Define the portable organization-foundation contract and platform distribution lock hygiene#42
• Generalize Holon into a portable organization bootstrapper for downstream consumers holon#41
• Existing Pace lock and fleet-convergence contracts
• Existing Observatory evidence/read-model work

Non-goals

• Centralizing multiple organizations into one canonical state store.
• Automatically merging pull requests.
• Creating repositories or GitHub organizations.
• Replacing consumer-specific policy with Ego Hygiene defaults.
• Publishing private downstream fleet metadata.