Defines typed feature flags with default-safe values, audited tenant and user targeting, an always-reachable kill-switch, and a cleanup date after which the flag must be removed.
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
Ship behavior changes behind typed flags whose default is the last known-safe path. Targeting may select tenants or users only through an audited rule set. A kill-switch overrides every targeting rule. Each flag carries a cleanup date; after that date the flag must be deleted from code and configuration rather than left as permanent branching.
Scope
- Flag schema, defaults, evaluation order, tenant and user targeting, percentage rollouts, kill-switch, change audit, client and server evaluation, and removal after cleanup.
- Progressive delivery of product behavior in backend services and web clients that share the same flag names.
- Emergency disable of a shipped path without a full artifact rollback.
Outside this block
- Traffic-weighted canary of a new binary, which is a release-routing decision.
- Experiment assignment and statistical analysis of metrics.
Contract
- Every flag declares type, default-safe value, owner, and cleanup date; unknown flags evaluate to the typed default, not to true.
- Evaluation order is kill-switch, then environment disable, then explicit deny, then targeting, then percentage, then default.
- Tenant and user targeting records actor, reason, and change time; anonymous clients cannot self-grant a restricted flag.
- The kill-switch forces the safe value globally within the configured propagation bound.
- Server evaluation is authoritative for authorization-sensitive paths; the web client may cache only flags marked client-safe.
- After the cleanup date, CI fails if the flag identifier still appears in code or runtime config.
Implementation guidance
- Generate accessors from a schema so callers cannot pass free-string flag names.
- Evaluate flags at the request or job boundary and pass a snapshot; do not re-read mid-request with a different result.
Failure handling
- If the flag store is unreachable, serve defaults and emit a high-severity signal; do not fail open to experimental behavior.
- Malformed targeting rules are skipped and the next step in evaluation order applies.
Verification and operations
- Measure default-fallback rate, kill-switch uses, flags past cleanup date, and disagreement between client cache and server snapshot.
- Alert when an authorization-sensitive flag is marked client-safe.
- Prove with tests that kill-switch beats a one-hundred-percent rollout and that unknown flags stay default-safe.
The executable-looking examples in this package are fixtures and acceptance contracts. Run
python tools/validate.py from the collection root to check package structure and metadata; then
implement and execute the scenarios in the target repository.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - The adopting team must map actors, data classes, error vocabulary, and ownership to its system.
References
- Flag schema, evaluation order, targeting audit, and cleanup dates are project decisions recorded in this package; they are not a public standard.