Flag lifecycle and intent

Every flag needs an owner, purpose, expected final state, and review point. Lifecycle metadata turns those expectations into visible cleanup signals without changing runtime evaluation automatically.

Use temporary lifecycle for work that should leave the codebase. Use permanent lifecycle only when the flag remains an intentional long-lived operational or product control.

Temporary and permanent

Temporary flags support releases, experiments, migrations, and maintenance. Give them a cleanup date and a note describing the final value and guarded code to remove.

Permanent flags support long-lived operational controls, entitlements, permissions, or configuration. They still need ownership and review, but age alone does not mark them cleanup due.

Do not mark a release flag permanent merely to suppress cleanup signals. Change lifecycle only when the product decision itself has become long-lived.

Choose intent

Intent	Use it for	Typical completion
Release	Gradually shipping one implementation	New branch becomes normal code
Experiment	Comparing defined variants	Winning branch ships or test ends
Ops	Emergency or traffic control	Remains owned and rehearsed
Permission	Experience by plan or role	Remains separate from authorization
Configuration	Runtime tuning	Remains bounded and validated
Maintenance	Migration or temporary platform work	Migration and flag are removed

Intent improves review and discovery. It does not affect evaluation precedence or grant permissions.

Record useful ownership

A good lifecycle note answers:

• Who decides the final state?
• Which code paths read the flag?
• What result should become the fallback?
• Which deployment removes the old branch?
• What signal allows cleanup?
• What is the rollback condition before completion?

Do not include secrets, raw customer identifiers, targeting values, or sensitive ticket content. Link to internal work only when readers have appropriate access.

Understand review signals

Temporary flags can be surfaced when they are:

• Past their cleanup review date.
• Globally on in production.
• Off everywhere after real traffic.
• Unused beyond the configured threshold.
• Left in a partial production rollout.
• Archived while guarded code may still exist.

These are prompts for review. FeatureGate never changes configuration or deletes application code because a flag looks stale.

Complete a temporary flag

1. Decide the intended permanent behaviour.
2. Make that value the environment fallback.
3. Remove targeting and rollout rules.
4. Observe the stable state.
5. Remove the obsolete branch and tests from application code.
6. Deploy and verify the cleanup.
7. Archive the flag after required callers stop depending on it.

Archive is not a substitute for code cleanup. It only changes the platform resource lifecycle. Callers may still contain dead branches and fallback assumptions.

Maintain permanent controls

Permanent operational flags need an owner, safe values, incident instructions, and periodic validation. Exercise kill switches before an incident and keep notifications routed to eligible builders.

Permanent permission flags may shape experience but must not become the only enforcement of access. The application remains responsible for authorization and entitlements.

Related pages: Review and clean up flags, Kill switches, and Tags and flag discovery.