# 1. Repair decision **Decision: FEATURE FLAG LIFECYCLE DRIFT FOUND — SAFE LOCAL PATCH AVAILABLE; live targeting remains unverified.** `checkout_v2` has conflicting fallbacks and variant names, exposure analytics fire on render, tests model only booleans, and `new_receipts` still guards old and new branches despite a supplied 100% rollout note. # 2. Scope and boundary **Reviewed:** registries, provider adapters, browser bootstrap, React hooks, API middleware, analytics, mocks, tests, docs, and rollout notes. **Not accessed:** LaunchDarkly environments, targeting rules, production identities, live events, customer sessions, or deployment systems. Local changes cannot authorize remote deletion or prove live variation delivery. # 3. Flag contract source register | Source | Behavior | Status | |---|---|---| | server registry | `checkout_v2` fallback `false` | Executable fallback | | browser registry | fallback `true` | Conflict | | API middleware | `legacy/new` | Server variants | | React hook | `control/treatment` | Client variants | | analytics helper | exposure on render | Measurement behavior | | test mocks | booleans only | Incomplete contract | | rollout note | `new_receipts` at 100% | Supplied claim | | code search | two receipt branches | Legacy path remains | # 4. Canonical repository contract The repository does not prove the approved fallback or variant vocabulary. Mark both **OWNER DECISION REQUIRED**. Structure: - one typed definition per flag; - key, kind, variants, fallback, owner, purpose, review date, and lifecycle state; - server and browser adapters consuming the same definition; - typed evaluation result with variation and reason; - exposure recorded at the behavior decision, not every render; - retirement only after permanent-path and rollback approval. # 5. Drift findings ## F1 — Fallback mismatch Server `false` and browser `true` can produce different behavior during provider failure or bootstrap delay. **Repair:** remove duplicated literals and import one approved fallback. ## F2 — Variant mismatch The API expects `legacy/new`; the UI expects `control/treatment`. **Repair:** define one variation union and an explicit provider-value map. Unknown values use the approved fallback and a structured diagnostic. ## F3 — Exposure inflation A render-level event may repeat and may count users before the flag changes behavior. **Repair:** add a decision helper that records once per stable flag, subject, and decision instance. Analytics semantics require approval. ## F4 — Weak mocks Boolean mocks cannot test variants, fallback reasons, missing context, or provider errors. **Repair:** create a typed evaluator fixture with variation, reason, context, and failure mode. ## F5 — Stale `new_receipts` branch A 100% rollout note is not enough to remove rollback code automatically. **Repair:** add characterization tests and a retirement checklist. Remove the legacy branch only after an owner confirms permanence and remote-flag handling. ## F6 — Missing lifecycle metadata Flags lack owners and review dates. **Repair:** add registry metadata and a test that rejects incomplete active definitions. # 6. Safe patch plan | Area | Change | |---|---| | Registry | typed definitions and lifecycle metadata | | Adapters | shared fallback and explicit variant mapping | | Consumers | typed variation branches | | Analytics | decision-boundary exposure helper | | Tests | evaluator fixtures and failure scenarios | | `new_receipts` | retirement gate and optional approved cleanup | | Docs | creation, rollout, review, retirement, remote boundary | No live targeting, release, remote deletion, or deployment is included. # 7. Deterministic test matrix 1. Server and browser use the same fallback. 2. Every approved variation reaches the correct branch. 3. Unknown values use the fallback and record a diagnostic. 4. Provider unavailable and missing-context cases are deterministic. 5. Rerenders produce one effective exposure event. 6. No event records when the flag does not affect behavior. 7. Fixtures represent variants and evaluation reasons. 8. Every active flag has owner and review metadata. 9. Retired flags cannot remain referenced outside approved compatibility code. 10. Receipt characterization tests preserve the selected path. 11. Approved cleanup leaves no raw key strings or dead imports. 12. Tests make no LaunchDarkly network calls. # 8. Verification steps Run: - `npm test -- feature-flags` - `npm test -- checkout-v2` - `npm test -- receipt-rendering` - `npm run typecheck` - `npm run lint` - `npm run build` Find raw flag keys, duplicated fallbacks, old variants, and direct exposure calls. # 9. Production boundary Unknown: live variations, targeting, cached bootstrap values, provider-outage behavior, analytics expectations, rollback needs, remote prerequisites, and mixed client versions. Remote cleanup and rollout sequencing need a separate operational plan. # 10. Human approval request **Safe now:** registry structure, shared consumers, typed mapping, evaluator fixtures, exposure helper, metadata checks, and retirement tests. **Decisions required:** fallback, canonical variants, exposure semantics, `new_receipts` permanence, rollback window, owners, and remote archival or deletion. **Status: PATCH READY FOR LOCAL REVIEW — LIVE TARGETING, ANALYTICS, AND RETIREMENT NOT VERIFIED** # 11. Suggested commit message `fix(flags): unify checkout variants and lifecycle metadata`