Feature-flag minimalism — born-in-prod, no legacy scaffolding

Decided: 2026-08-24 · By: PO (Alfredo Pacheco) · Status: binding Eventual home: user/tech manual (terminales-docs). This file is the interim record so we don’t lose it.

Principle

We have not shipped to prod/live yet. Until we do, there is no legacy path to preserve.

1. Build only the final path. Do not add or retain scaffolding whose only job is to support a superseded path — dual-shape adapters, rollback branches, “not-yet” fallbacks — beyond the short window needed to land a change safely.
2. Born in prod with only strictly-necessary flags. A feature flag is strictly necessary only if it gates something that must be independently toggled in production — a genuinely optional capability or a kill-switch for a risky integration. A flag that merely stages a migration we have not shipped yet is not necessary; it is transitional and must be collapsed before launch.
3. Sweep the agentic-workflow flags. The pipeline introduced many FEATURE_FLAG_* / feature_flag_* flags. Before the prod cutover, audit every one across api / web / mobile and either justify it as strictly-necessary or delete it (flag + both branches).

Superseding note: the earlier “all feature flags ON for MVP” directive (2026-07-14) turned the ramp off. This is the next step — the flags themselves come out for prod birth, not just switched on.

Applies now — settlement consolidation

• feature_flag_settlement_unified (env FEATURE_FLAG_SETTLEMENT_UNIFIED, api) is a migration flag, not a product flag. Unified is THE settlement path from day one. Before prod, collapse to unified-only: remove the flag, the legacy settlement path, and the per-order settlementModel=legacy branch. The settlementModel lock exists to make the migration safe — once there is no legacy path, it too can go.
• Mobile client dual-shape handling is transitional scaffolding: the legacy Captured branch, and the “el cobro se registró; finaliza desde Ventas” guards in the Manual/Split card view-models. Once unified is the default and the legacy tail is deleted server-side, simplify the client to the settling path only, and finish full settling-observe for Manual/Split (drop the interim guard).

Why

Carrying dual paths and migration flags into prod is cost with no pre-launch benefit: it doubles the surface to test and maintain and invites the exact class of drift — project-id, stale env, path divergence — that has already cost us time. Pre-launch, the cheapest correct system is the one that only ever had one path.

How to apply

• New work targets the final path directly. Add a flag only for an independently-toggleable prod capability or a real kill-switch.
• When a migration flag is needed to land a change safely, file its removal as a same-wave follow-up, never a permanent fixture.
• Before prod cutover: grep -rn "FEATURE_FLAG_\|feature_flag_" across api, web, mobile → justify each survivor or delete it.