0032. Generalizing Org Reconciliation Across the Fleet¶

Status: accepted
Date: 2026-07-11
Deciders: lusoris
Related: PR #2260

Context¶

The paperclip-org-reconciler applied a declarative, idempotent GitOps org model to the Northlight org only. As the revenue fleet grew to several orgs, each new org needed the same reconciliation guarantees — declared goals, projects, agents, skills, and environment reconciled from a single source of truth — but the reconciler logic was Northlight-specific and could not be reused without copy-paste drift.

Decision¶

Generalize the reconciler so it applies a well-formed org model to every org in the fleet, driven by a per-org configuration file (files/orgs/*.json) rather than a single hard-coded Northlight config. Org-specific values (marker prefix, repository ref default, goals and projects, environment) are parameterised, and Northlight's existing behaviour is preserved through defaults so its reconciliation is unchanged. A class default bounds every org's long-lived heartbeat sessions without editing each org config.

Alternatives considered¶

One bespoke reconciler per org: multiplies maintenance and guarantees drift between orgs as fixes land unevenly.
Manual API configuration per org: non-declarative and non-idempotent, which is exactly what the Northlight reconciler was built to avoid.

Consequences¶

A single reconciler covers the whole fleet; onboarding an org is a new orgs/*.json plus registration, not new code.
Shared fixes and safety checks (stale-config refusal, create-on-missing markers) apply uniformly to every org.
Northlight-shaped configs remain special-cased only where genuinely unique (for example the portfolio project), keeping the general path clean.

References¶

PR #2260 — feat(paperclip-dispatcher): reconcile the whole org fleet, not just Northlight
apps/ai/paperclip-dispatcher/files/org_reconciler.py, apps/ai/paperclip-dispatcher/files/orgs/*.json, apps/ai/paperclip-dispatcher/templates/org-reconciler.yaml