# ADR-0002: Kit mirror is one-way pull from {{platform_team_name}}/ai-kit; never push back

- **Date:** 2025-11-04
- **Status:** accepted
- **Reversibility:** medium (could be reversed if mirror-direction-bidirectional becomes the org-wide pattern; would require Platform Engineering coordination and likely a new RevOps-AI -> Platform contribution review process)
- **Deciders:** RevOps-AI eng lead, {{platform_eng_lead}} (Platform Engineering), {{exec_vp_revops}} (kit-mirror cost approval)
- **Scope:** instance (also affects {{platform_team_name}}/ai-kit governance posture)

## Context

ADR-0001 chose to build the enrichment service consuming `{{platform_team_name}}/ai-kit`. The kit-mirror direction question arose immediately: do we mirror one-way (pull only; treat the kit as upstream truth) or two-way (allow pushback when this team improves a component)?

Two-way pushback would let RevOps-AI ship improvements faster (no waiting for Platform Engineering to integrate); but it introduces governance complexity (whose changes win on conflict? how does Platform Engineering review external contributions?).

Upstream constraints:

- L4 platform kit posture is `mature-internal-mirror` (Q6 from localization)
- Platform Engineering's stated kit-mirror policy is one-way; they explicitly do not accept inbound contributions to the kit's primary surface
- BOOTSTRAP-BRIEF Section II describes the kit-mirror pattern as one-way by default (`Kit + mirror pattern... One-way sync. Improvements flow kit to consumer on re-sync.`)

## Decision

Kit mirror is strictly one-way: `{{platform_team_name}}/ai-kit -> mql-enrichment-service/kit`. Pull only. Improvements that emerge in this team flow back to {{platform_team_name}} via the inbox-outbox pair (capability requests), not via direct contribution.

## Options considered

### Option A: One-way pull only [CHOSEN]

- **Summary:** This team mirrors from `{{platform_team_name}}/ai-kit` on biweekly cadence; never pushes back. Improvements proposed via inbox-outbox to Platform Engineering; they decide whether to integrate
- **Pros:**
  - Clear governance boundary; Platform Engineering owns the kit; this team owns the consumption
  - Platform Engineering can review every change before integration; quality stays consistent across consumers
  - This team's extensions (locally-owned components like `kit/contracts/enrichment-record-schema.json`) are clearly separated from upstream-mirrored components; the boundary is enforced by `MIRRORED FROM` headers
  - Matches BOOTSTRAP-BRIEF Section II default pattern; reduces governance surface
- **Cons:**
  - Improvements that this team makes locally cannot flow back as fast as we might want; Platform Engineering's intake process adds latency
  - Some local extensions may duplicate work other consumers also need; without a contribution path, every consumer reinvents

### Option B: Two-way with upstream review

- **Summary:** Pull from `{{platform_team_name}}/ai-kit`; this team's improvements may be proposed as PRs against the kit; Platform Engineering reviews and accepts or rejects
- **Pros:** Improvements flow back faster; less duplication across consumers
- **Cons:** Governance complexity (review SLAs, conflict resolution); Platform Engineering does not currently have the bandwidth for inbound contribution review; would require a new Platform-Engineering-side process; risk of inconsistent quality across PR sources

### Option C: Fork-and-diverge

- **Summary:** Mirror once, diverge from there; this team maintains the kit independently
- **Pros:** Maximum local control; no upstream coordination needed
- **Cons:** Loses the platform-kit pattern entirely; this team becomes its own platform team; no compounding benefit from shared kit improvements; explicitly rejected by Platform Engineering as a precedent risk

## Rationale

Option C is rejected on org-wide platform-kit policy grounds. Option B is feasible eventually but premature: Platform Engineering does not have the intake-review bandwidth, and forcing it would consume Platform-Engineering capacity from kit-improvement to inbound-review. Option A is the simplest pattern that respects governance boundaries and matches the org-wide kit-mirror precedent.

The tradeoff explicitly accepted: improvements this team makes locally take longer to flow back than they would in Option B. Mitigation: locally-owned components (those that genuinely should not be in the upstream kit, like our enrichment-record schema) stay local with no `MIRRORED FROM` header; mirror discipline applies only to components that came from the kit. This way, "local improvements" are clearly distinguished from "kit components we extended."

## Consequences

### Positive

- Clean governance boundary; ownership clear
- Mirror discipline enforceable via `MIRRORED FROM` headers and the `architect-kit-mirror` skill
- Locally-owned components clearly separated from upstream
- Platform Engineering capacity preserved for kit improvement, not inbound review

### Negative

- Improvements take longer to flow back to upstream
- Some consumer-team duplication across the org (acceptable; visibility is good; eliminating duplication is a Phase 2 problem after the kit-mirror pattern matures)

### Followups

- Establish inbox-outbox pair with {{platform_team_name}} for capability requests and kit-sync events (`inbox/from-{{platform_team_name}}.md` and corresponding outbox)
- Integrate `architect-kit-mirror` skill from the deployment kit; biweekly sync cadence
- Catalog locally-owned components in `kit/PLATFORM-KIT.md` "Locally-owned components" section so the boundary is visible

## Cross-references

- Layer this decision affects: L4 (platform kit)
- Related ADRs: ADR-0001 (build vs buy)
- BOOTSTRAP-BRIEF Section II (kit + mirror pattern)
- `kit/PLATFORM-KIT.md` (mirror manifest and drift discipline)
- `inbox/from-{{platform_team_name}}.md` (the inbox this decision creates)
