How the Engine Works

FlagShark combines source analysis, provider evidence and a controlled change lifecycle. Each stage answers a different question; success at one stage does not imply support for the next.

Inventory: what source contains

Pull-request analysis describes proposed changes. Default-branch scans and merged changes maintain repository inventory. Inventory is scoped to scanned files, supported patterns and the recorded revision; ignored files, unresolved calls and incomplete scans limit what can be concluded.

The language catalog describes detection patterns. It is not a migration or retirement certification matrix. Flag age is a prioritization signal, not proof that a flag always serves one value.

Assessment: what can be changed

Migration assessment resolves source API usage, imports, client provenance and the applicable versioned support contract. Provider-backed evidence and code-only evidence remain distinct. Unsupported behavior must produce a blocker or explicit scope limitation.

Cleanup additionally needs a supported retirement shape, policy eligibility and trustworthy terminal-value evidence from the configured backend. Permanent flags, exclusions, missing authorization and unknown values can block an otherwise parseable call.

Plan and preview: what will change

An immutable plan ties the proposed edits to source, profile and recipe identities. The user inspects that concrete change. Source drift requires reconciliation rather than silently publishing different bytes.

OpenFeature adoption changes the application API and its supported setup/context/dependencies while retaining the selected runtime backend. Retirement substitutes a proven terminal evaluation and simplifies the affected source. Piranha supplies structural rewriting for registered recipes; parser support alone does not enable a whole language/provider combination.

Custom detection patterns and repository profiles have different trust levels. Custom libraries require semantic evidence and an admitted contract before transformation.

Validation and publication

The declared validation contract determines the required parse, typecheck, test and CI checks. A missing required check is a blocker. Local synthetic fixtures, real-SDK fixtures and deployed GitHub/provider runs are different evidence levels.

Publication consumes the exact reviewed preview with authorization, drift and replay controls. Current pre-GA paths publish draft PRs. Humans review and merge through normal repository controls; FlagShark does not automatically merge.

Verification and repeat work

For a support cell with verification capability, the service checks the actual default branch after merge and records bounded residual evidence. UI states should distinguish a draft, CI failure, merge pending and verified result.

Migration verification retains source API and runtime backend identity separately. A dashboard display join is useful visibility but is not proof of durable cleanup enrollment. As of September 9, 2026, OpenFeature retirement is registered through draft PR and the complete post-adoption verified cleanup loop remains under certification.

Recurring scheduling is constrained by current source, provider evidence and workspace policy on every cycle. Consult cleanup PRs for current limits and OpenFeature adoption for the scoped migration journey.