# Flag lifecycle and intent

Classify flags, set cleanup reviews, and keep release controls from becoming permanent debt.

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.

![Flag purpose choices and generated cleanup review date](/images/model-purpose.png)

## 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](/docs/operate/review-and-clean-up-flags),
[Kill switches](/docs/operate/kill-switches), and
[Tags and flag discovery](/docs/flags/tags-and-discovery).