# Pathrule Pattern: Feature Flags and Progressive Delivery (1.0.0) # ::pathrule:package:feature-flags-progressive-delivery ### [RULE] Evaluate flags through one typed boundary (path: /src/flags) Every flag has a declared type, stable key, owner, purpose, safe default, lifecycle, and evaluation adapter. Scattered provider calls and string keys produce inconsistent defaults, missing context, and behavior that cannot be found or retired reliably. Enforce this boundary in /src/flags so invalid work stops before it reaches another subsystem or creates an externally visible side effect. - Expose typed application functions instead of raw SDK calls or provider flag keys in feature code. - Validate returned values and fall back to the declared safe default on missing, malformed, timeout, or provider error states. - Emit evaluation reason, variant, provider, context class, and flag version without logging sensitive targeting attributes. - Keep authorization and durable entitlement decisions outside feature flags unless a separate authoritative policy enforces them. Verification: Disable the provider and return missing, malformed, and wrong-type values; confirm every caller receives the same safe behavior and telemetry reason. --- ### [RULE] Roll out by stable subjects with a measured rollback (path: /src/features) Cohorts use server-derived stable targeting keys and each rollout step has success, failure, pause, and rollback signals. Random or mutable client attributes move users between variants and can hide regressions by changing the population during measurement. Enforce this boundary in /src/features so invalid work stops before it reaches another subsystem or creates an externally visible side effect. - Choose the subject that owns the experience, such as user, account, device, or request, and keep it stable for the rollout's duration. - Start with internal or low-risk cohorts, then expand only after a defined observation window meets product and reliability guardrails. - Compare treatment and control on user outcomes, errors, latency, support, and data integrity, not only flag evaluation counts. - Make kill-switch behavior fast, permissioned, audited, and tested before exposure begins. Verification: Replay the same subjects across devices and services, simulate provider failure and regression signals, and confirm assignment stability plus immediate safe rollback. --- ### [MEMORY] Targeting context is a data contract (path: /src/flags) Evaluation context can include identity, tenant, locale, environment, or device data, so inconsistent naming and precedence change who receives a feature. Define allowed fields, types, sources, sensitivity, and merge precedence centrally. Derive authoritative fields on the server and pass only the minimum attributes required by targeting rules. Use one canonical targeting key for deterministic allocation and never repurpose it mid-rollout. Version context changes that can alter cohorts and test them against recorded evaluation fixtures. Keep the decision explicit at /src/flags; moving it into an incidental caller makes behavior depend on which route happened to execute first. See /src/features for product behavior and the progressive rollout skill for cohort decisions. That related boundary consumes this decision and carries the evidence that proves it still holds. --- ### [MEMORY] Every flag has a removal state (path: /src/features) A flag is temporary control-plane state unless it represents a long-lived operational setting with explicit ownership. Record creation reason, owner, expected decision date, cleanup condition, and code locations when the flag is introduced. After full rollout, remove the losing branch, provider configuration, telemetry, tests, and compatibility code in one tracked cleanup. After rollback, remove the failed branch or open a new experiment with a new hypothesis rather than leaving ambiguity. Review permanent operational flags separately for access, audit, defaults, and disaster behavior. Keep the decision explicit at /src/features; moving it into an incidental caller makes behavior depend on which route happened to execute first. See /src/flags for registry metadata and /.github/workflows for cleanup enforcement. That related boundary consumes this decision and carries the evidence that proves it still holds. --- ### [SKILL] run-progressive-rollout (path: /) --- name: run-progressive-rollout description: Run a feature rollout through readiness, stable cohorts, guardrail checks, pause, rollback, and flag retirement. --- # Run Progressive Rollout Run this procedure whenever the governed surface changes or its operational evidence becomes stale. 1. Confirm the flag owner, safe default, targeting subject, treatment and control behavior, telemetry, support plan, and tested kill switch. 2. Define cohort steps, observation windows, success metrics, reliability and safety guardrails, and the authority to pause or roll back. 3. Expose internal and low-risk cohorts first, verify stable assignment and data quality, then expand one step at a time with recorded decisions. 4. Choose ship or rollback, remove the unused branch and flag configuration, and verify no stale evaluation or targeting data remains. Record the decision, failed checks, and follow-up owner with the change. A successful run leaves reproducible evidence that another reviewer can inspect without repeating the investigation from memory.