feat: Update rollout documents and work items for UIKit-removal spike, clarifying consumer communication and validation expectations

ai/logs/2026-04-14.md

@@ -0,0 +1,44 @@
+# 2026-04-14
+
+## Previous Workday Refresh
+
+- `PDIAP-14859` rollout draft remained in revision on April 13 rather than being finalized; the work was limited to the specific draft changes requested in review, not a broad rewrite.
+- The rollout document should rename the proposed flag from `xflow-master-swiftui-enabled` to `xflow-swiftui-enabled`.
+- The first rollout phase should explicitly mention contacting consumers ahead of time and asking them to validate their flows in `XQ1`.
+- The rollout document should remove overly technical wording and avoid implying there are no consumer-side changes without qualification.
+- Current spike clarification: `FTTransfer` changes are no longer considered strictly required after applying the SwiftUI dismissal behavior correctly, but risky entry points still need explicit rollout coverage.
+
+## AO / Discourse Findings
+
+- The AO reply about `TeenIdentityCheck` was approved and sent after clarifying that `CheckIdentity` was already correct and that the `TeenIdentityCheck` issue was the missing `validations` root and missing `eighteenOrAbove` inside `validation-rules`.
+- Later validation showed two distinct authenticated scenarios rather than one uniform cross-platform issue.
+- A `HybridBrokerage` scenario reproduces on both iOS and Android.
+- A Youth flow (`Open an account` -> `Save & Invest for a child` -> `Fidelity Youth Account`) fails on iOS while working on Android.
+- Current evidence suggests Android is more flexible when decoding rule variations, while iOS is stricter about the expected `validation-rules` structure in the Youth-flow scenario.
+- The iOS-only Youth-flow discrepancy is the scenario currently aligned with the story-level client fix.
+- The cross-platform `HybridBrokerage` scenario should stay scoped separately until it is clear whether it is a service/config issue or a distinct bug.
+
+## Current Direction
+
+- `PDIAP-14859` remains focused on incorporating rollout-document feedback and publishing a consumer-facing plan.
+- `PDIAP-15838` remains the next implementation story after the rollout-document work is in a good state.
+
+## New Investigation Note
+
+- For the Murali group discussion, there appears to be usage of `ApexBridgingAddressComponent` through references in `XFlowPageApexItem`.
+- If that usage is active, the dependency comes from `ApexKitV3`, which was expected to retain support after the earlier ApexKit removal.
+- Current guidance from that discussion is to migrate toward `FDS` or `ApexKitSwiftUI`, but the exact replacement for `ApexBridgingAddressComponent` is still unclear and needs investigation and validation.
+- Narrower wording for the current status: there are visible references at a glance, but it is not yet confirmed whether they are active or dead code; the next step is to validate with a run.
+
+## Fresh Mattermost Sync
+
+- Confirmed with breakpoints that `ApexBridgedAddressComponent` is not used when loading an address component; the observed path goes through `ApexGoogleAddressViewModel`.
+- A follow-up review raised that the old component may still be used to load rules and appears in `XFloaValueChanger`, so it should not be treated as dead code without deeper verification.
+- Current direction for that investigation is to be exhaustive and avoid assumptions before describing the old bridged path as unused.
+- Clarification from the same thread: the remaining `ApexKitV3` reference does not cause build issues because `ApexKitSwiftUI` still depends on `ApexKitV3`.
+- `PDIAP-14859` rollout-document follow-up: Jeff asked whether the FTTransfer section needed updating, and David confirmed the document had already been revised to clarify that root cause.
+- Latest clarification in the Murali thread: `ApexBridgedAddressComponent` belonged to the old UIKit rule-handling flow. In the current implementation, rules are described as being handled through the SwiftUI path, parsed from the payload and applied through the `XFlowViewApadater` / `ViewModelAdapter` layer using `ApexGoogleAddressViewModel`.
+- Clarification for the retro/ownership discussion: the earlier FTTransfer-side explanation was not fully wrong, but it was incomplete. The SwiftUI state behavior was a real symptom/effect on the consumer side; the deeper root cause was the dismissal flow handling that had not been covered correctly. The main gap was concluding consumer ownership before isolating that underlying dismissal root cause.
+- Suggested clarification for Jeff and Aylwing: the dismissal issue should be framed as a corner case that was not simple to identify without deeper analysis. The FTTransfer-side SwiftUI behavior was still a real observed symptom, but the deeper root cause only became clear after more thorough investigation.
+- Additional clarification for that same reply: the FTTransfer-side state-management behavior should be described as a real SwiftUI anti-pattern that can cause view/state identity loss. That behavior was valid to call out, but it still did not fully explain the deepest root cause until the dismissal-path analysis was completed.
+- Jeff clarified the broader lesson: if ownership is still uncertain, the safer path is to roll back and continue investigating rather than make confident claims about consumer-side fault before the code is fully understood. The risk is loss of trust and reduced ability for the framework team to make authoritative calls independently.

ai/state/current.md

@@ -10,6 +10,8 @@
 - Finalize `PDIAP-14859` with a dual UIKit/SwiftUI plan that removes `UIHostingController` dynamically while preserving both flows appropriately
 - Prioritize `PDIAP-15838` next; `PDIAP-15836` comes later
 - Include feature-flag planning for the broader UIKit-removal spike, including dismissal sequencing changes that affect consumers
+- Thoroughly verify current `ApexBridgingAddressComponent` / rule-loading usage before describing it as inactive or dead code
+- Reconcile the old UIKit address-rule path with the current SwiftUI handling path through the adapter/view-model layer before reporting final ownership or replacement guidance
 - The process-oriented rollout document for the UIKit-removal spike has been drafted and sent to Jeff for review
 - The rollout document should frame the work as a more deliberate migration phase toward the SwiftUI-only path, not as a correction to a prior failed attempt
 - The rollout document should make clear that the migration plan uses a dual-path pattern to switch between the `UIHostingController` path and the SwiftUI-only path during rollout
@@ -20,6 +22,8 @@
 - Broad XQ1 validation is a required gate before any production enablement
 - The document should explicitly mention applying architectural improvements learned from prior SwiftUI iterations, especially where earlier approaches introduced anti-patterns
 - The rollout document should stay concise and avoid an overly complex phase model
+- The rollout document needs one more revision before publishing, including the `xflow-swiftui-enabled` flag name, clearer first-phase consumer contact and `XQ1` validation language, and removal of overly technical wording
+- Re-check the authenticated AO validation issue with scenario-specific evidence: the Youth `TeenIdentityCheck` path currently points to an iOS-only decoding gap, while a separate `HybridBrokerage` case reproduces on both platforms
 
 ---
 
@@ -35,6 +39,9 @@
 - Defining a consumer rollout plan for UIKit-removal sequencing changes, including validation, communication, and feature-flag retirement
 - Keeping the consumer-facing rollout document aligned with the actual global-flag rollout model and broad XQ1 validation requirement
 - Incorporating Jeff's pending review feedback on the `PDIAP-14859` rollout draft once it arrives
+- Avoiding assumptions when comparing iOS and Android validation behavior; scenario-specific parity needs to be confirmed before reporting scope
+- Avoiding assumptions about legacy Apex/ApexKit paths; breakpoint evidence and helper usage both need to be reconciled before reporting ownership or replacement guidance
+- When ownership is still uncertain under production pressure, prefer rollback-plus-investigation framing over confident blame assignment to consumers
 
 ---
 
@@ -50,6 +57,7 @@
 - Standups should omit items not tied to a story unless they are real blockers
 - Manager updates should be short, precise, and natural in English
 - Mattermost messages should make scope and next action explicit
+- When root cause is not fully isolated, do not position framework conclusions as authoritative consumer-side fault
 - Standups should be written as David's external progress report and should not mention Jeff by name
 - Standups should never mention Mattermost because it is internal-only communication
 

ai/state/work-items.md

@@ -10,7 +10,7 @@ Update the per-ticket files first when scope, status, sequencing, or communicati
 
 - `PDIAP-14859` - Spike - Research strategy to remove final UIKit wrapping from XFlowSDK and XFlowViewMaker without disrupting consumer implementation
   Detail: `ai/work-items/pdiap-14859.md`
-  Current note: rollout draft has been shared with Jeff for review; scope centers on the dual UIKit/SwiftUI path, dynamic `UIHostingController` removal, global feature-flag rollout, and broad `XQ1` validation.
+  Current note: rollout draft has been reviewed; next revision should incorporate the `xflow-swiftui-enabled` flag name, explicit first-phase consumer contact and `XQ1` validation, and tighter consumer-facing wording before publishing.
 
 - `PDIAP-15838` - Remove Apollo for iOS
   Detail: `ai/work-items/pdiap-15838.md`
@@ -22,4 +22,4 @@ Update the per-ticket files first when scope, status, sequencing, or communicati
 
 - `PDIAP-15765` - AO DOB field error not showing investigation
   Detail: `ai/work-items/pdiap-15765.md`
-  Current note: authenticated-only `TeenIdentityCheck` DOB issue with root cause documented; waiting for the right closure timing.
+  Current note: authenticated AO validation work now has two scenarios: an iOS-only Youth `TeenIdentityCheck` decoding gap and a separate cross-platform `HybridBrokerage` case that should stay scoped separately.

ai/work-items/pdiap-14859.md

@@ -19,7 +19,7 @@
 
 - Define a consumer-facing rollout plan for the broader UIKit-removal work.
 - Preserve both UIKit and SwiftUI paths appropriately while introducing the new path safely.
-- Cover risky entry points such as `FTTransfer`.
+- Cover risky entry points such as `FTTransfer`, while keeping the latest spike finding explicit that consumer-side changes there may no longer be strictly required after the SwiftUI dismissal behavior is applied correctly.
 - Include validation expectations in `XQ1`.
 - Use a global feature-flag rollout model rather than entry-point-based enablement.
 - Include consumer communication expectations.
@@ -33,7 +33,9 @@
 - The feature-flag and rollout planning guidance applies to the broader UIKit-removal spike, not only to dismissal-sequencing work.
 - Jeff suggested sending the process-oriented rollout document to Quy for feedback when ready.
 - The draft shared with Jeff already reflects the global feature flag, broad `XQ1` validation, and consumer-facing rollout flow guidance.
-- Await Jeff's review feedback before treating the rollout framing as final.
+- Additional review feedback from April 13: rename the proposed flag to `xflow-swiftui-enabled`, make consumer contact and `XQ1` validation explicit in the first phase, remove overly technical rollout wording, and avoid implying there are no consumer-side changes without qualification.
+- On April 14, Jeff asked whether the FTTransfer part of the rollout document also needed updating; David confirmed the document had already been revised to clarify that root-cause section.
+- Await final follow-up after incorporating the latest review feedback.
 
 ---
 

ai/work-items/pdiap-15765.md

@@ -20,12 +20,17 @@
 - Root cause was documented.
 - The original external report was incomplete.
 - For the config discussion, `CheckIdentity` was already correct. The `TeenIdentityCheck` issue had two config gaps inside `validation-rules`: the root key should be `validations`, and the age gate also needs `eighteenOrAbove` there when that rule is required.
+- Follow-up validation on April 13 showed two distinct authenticated scenarios rather than one uniform cross-platform issue.
+- A `HybridBrokerage` scenario reproduces on both iOS and Android.
+- A Youth-flow `TeenIdentityCheck` scenario works on Android but fails on iOS.
+- Current evidence suggests Android is more flexible in how it decodes rule variations, while iOS is stricter about the expected `validation-rules` structure.
 
 ---
 
 ## Current Guidance
 
-- Treat the issue as scoped and understood unless new evidence appears.
+- Treat the iOS-only Youth-flow discrepancy as the main client-side issue currently aligned with the story.
+- Keep the cross-platform `HybridBrokerage` scenario separate until it is clear whether it is a service/config issue, a distinct bug, or an unreported rule-processing difference.
 - Keep the authenticated-user qualifier whenever this ticket is mentioned.
 - Do not describe it as a generic validation issue without the `TeenIdentityCheck` and auth context.