Terraform and OpenTofu drift convergence

Drift convergence is the controlled response to a detected difference between declared and live infrastructure. Forgeplane does not silently correct live resources: it creates a request-based workflow with feature gates, preview evidence, and approval hooks.

Before requesting convergence

1. Confirm that the finding belongs to the intended instance and environment.
2. Review the evidence, severity, observation count, and latest plan result.
3. Confirm that the instance’s template version, inputs, connections, and managed-state context are still valid.
4. Check the environment feature gate for the requested action.
5. Use Approval workflows when the resulting run requires a separate reviewer decision.

A finding is not permission to mutate infrastructure. The action must be supported, enabled, authorized, and eligible for the current instance state.

Supported convergence actions

Action	Behavior	Availability
revert_live	Requests a convergence run that moves live infrastructure toward declared configuration.	Executable today.
manual_ack	Acknowledges the finding without automated remediation.	Supported finding workflow.
accept_live	Would accept live state as the expected baseline.	Reserved; request returns a conflict.
codify_live	Would export live state into code artifacts for review.	Reserved; request returns a conflict.
Suppress / reopen	Controls whether a finding is intentionally silenced or revisited.	Finding lifecycle operations.

Only revert_live can start an executable convergence path. The data model and planned UI may contain the other action types, but they do not authorize behavior that is not implemented.

Revert-live flow

When revert_live is enabled and authorized:

1. Forgeplane accepts a convergence request for the finding.
2. The coordinator creates a preview or convergence run using the instance context.
3. The resulting evidence is reviewed according to the environment’s approval policy.
4. An approved run moves live infrastructure toward the declared configuration.
5. The finding and run retain the evidence and outcome for follow-up.

A disabled gate or failed eligibility check stops the request. It does not accept the live change, discard the finding, or fall back to an unreviewed mutation.

Feature gates

Convergence actions are gated per environment. Enable the relevant gate before attempting an action:

Feature gate	Controls
drift_convergence.revert.enabled	Allows revert_live actions.
drift_convergence.accept.enabled	Reserves accept_live in the data model and UI; execution is not available.
drift_convergence.codify.enabled	Reserves codify_live in the data model and UI; execution is not available.
drift_convergence.destructive.enabled	Allows destructive convergence operations.

The gate controls eligibility. It does not replace authorization, approval, state validation, or evidence checks.

Finding lifecycle

Each finding progresses through defined states:

An open finding moves to resolution_pending. It then becomes resolved or suppressed. A resolved finding that appears again becomes reopened, then returns to resolution_pending.

State	Meaning
open	Drift was detected and is awaiting action.
resolution_pending	A convergence action was initiated.
resolved	The finding was closed through a reviewed workflow.
reopened	A previously resolved finding appeared again.
suppressed	The finding was intentionally silenced.

Evidence and deduplication

Each finding can contain evidence records describing the observed difference:

Field	Purpose
kind	Type of evidence, such as an attribute change or missing resource.
ref_type / ref_id	Identifies the referenced evidence object.
excerpt	JSON payload containing the difference details.
captured_at	Time the evidence was recorded.

Forgeplane tracks a drift fingerprint, scope key, observation count, and confidence score. These fields help distinguish repeated observations from a new difference and preserve the reasoning behind a convergence request.

Severity and boundaries

Findings use low, medium, or high severity. Severity helps prioritize review; it does not bypass gates or approval.

Convergence is not an instant rollback and does not rewrite the source plan or silently accept live state. For managed-state recovery, complete the managed-state recovery workflow before requesting a state-changing operation.