docs(experiments): spec for UVE integration behind a dedicated flag (#37005)

[oidacra]

Proposed Changes

• Adds specs/37005-experiments-uve-integration/spec.md — the Spec-Kit specification for Experiments Portlet — UVE integration behind FEATURE_FLAG_EXPERIMENTS_PORTLET + variant Edit Content round-trip #37005. Spec only; the implementation lands in this same PR.

The spec covers two halves of the work: switching the Universal Visual Editor's Experiments entry point to the new portlet behind a runtime switch, and completing the portlet's Variants card with the Edit Content round-trip into UVE.

Three premises in the issue did not survive contact with the code. Each is resolved in the spec as D1/D2/D3, and both #37005 and #37008 were corrected on GitHub to match.

D1 — the flag named in the issue is not free. The issue proposed reviving FEATURE_FLAG_EXPERIMENTS, described as "declared, zero consumers today". That holds for the frontend enum entry only. The property is the live backend kill-switch for the whole Experiments feature — ConfigExperimentUtil.isExperimentEnabled(), gating experiment JS injection (ExperimentWebAPIImpl:338) and experiment resolution during page render (HTMLPageAssetRenderedAPIImpl:176,239). Setting it to false, the issue's intended default, would stop running experiments from serving to visitors. The spec requires a new dedicated switch, FEATURE_FLAG_EXPERIMENTS_PORTLET, shipped explicitly false. The explicit default is required rather than optional: getFeatureFlags() and withFlags() both map an absent flag to enabled, so a merely-declared flag ships on.

D2 — the flag-on destination. The issue deferred it. The spec settles it as the site-wide list filtered to the page in hand, with defined behavior for zero, one and many experiments, and a filter the editor can clear.

D3 — no "edited" signal. The issue asked a variant's meta line to read "Edited in the Universal Visual Editor". No such signal exists on the variant model on either side of the wire, and the legacy per-page card shows no edit indication at all. The spec forbids inventing one. It does require the consequence: the new Variants card renders the fixed string No content changes yet for every non-control variant, true today only because the Edit Content button beside it is disabled. This work is what makes it capable of being false, so the claim has to go.

Checklist

• Tests — none yet; this PR is spec only. Test-first per Constitution Principle V applies when implementation starts.
• Translations — no user-facing strings added. One existing key (experiments.configure.variants.meta.variant) is flagged for rewording at implementation time.
• Security Implications Contemplated — no new surface. The spec explicitly protects the existing visitor-facing experiments kill-switch from being repurposed or disabled (FR-014, FR-015a), which is the security-relevant risk here.

Additional Info

• Spec review page: https://claude.ai/code/artifact/8deabd7c-6fb0-40a1-9241-7f5c111ec019
• Depends on Experiments Portlet — Screen 1: portlet base + site-wide List #36989 (Screen 1), Experiments Portlet — Screen 2: Create/Update (/experiments/new + /:id/configuration) #37003 (Screen 2 — delivers the Variants card this work completes), Experiments Portlet — Screen 3: View Results #37004 (Screen 3).
• Migration Experiments Portlet — migration: delete the old per-page experiments UI and remove the flag #37008 retires FEATURE_FLAG_EXPERIMENTS_PORTLET, not FEATURE_FLAG_EXPERIMENTS.
• Open question with PM/PO: whether the UVE Experiments button keeps today's behavior. If the answer changes D2, FR-021a-c, US3 and SC-009 move before implementation starts.
• 34 functional requirements, 9 success criteria, 4 user stories, 9 edge cases. No open [NEEDS CLARIFICATION] markers.

Closes #37005

[claude]

Claude finished @oidacra's task in 52s —— View job

---

I'll analyze this and get back to you.

[erickgonzalez]

Feedback:

• Missing user story to turn off the FF in case something goes wrong