feat: Refactor work item management and documentation for clarity and structure

ai/AGENTS.md

@@ -71,7 +71,7 @@ When drafting messages for a manager or stakeholder:
 - Auto-promote direct user-provided project facts when they are clearly project-relevant, explicit, and useful for future sessions
 - Default promotion target is today's log
 - Promote to `ai/state/current.md` only when the fact changes the active work window
-- Maintain `ai/state/work-items.md` with explicit Jira IDs, approved titles, and currently relevant scope/status notes
+- Maintain `ai/work-items/` as the canonical memory for active Jira-linked work and keep `ai/state/work-items.md` as the quick summary layer
 - Promote to `ai/context/project.md` only when the fact is durable beyond the current work window
 - Use `ai/context/project.md` as the overview only; put system-specific, workstream-specific, and process-specific durable context in the corresponding subdirectory
 - Maintain `ai/context/people/` when repeated names, roles, or stakeholder relationships become useful for future sessions

ai/context/process/context-maintenance.md

@@ -13,7 +13,8 @@ Keep this workspace useful as living memory instead of a pile of disconnected no
 - Use the smallest correct destination:
   - `ai/logs/YYYY-MM-DD.md` for daily progress and evolving findings
   - `ai/state/current.md` for near-term active work
-  - `ai/state/work-items.md` for Jira-linked active work
+  - `ai/work-items/*.md` for canonical Jira-linked active work
+  - `ai/state/work-items.md` for the compact active-work summary
   - `ai/context/` for durable project knowledge
   - `ai/context/people/` for named person context
 

ai/state/current.md

@@ -6,7 +6,7 @@
 - Track REST migration findings
 - Debug Discourse and AO issues
 - Prepare better updates for the current manager or stakeholder through Mattermost
-- Follow up on `PDIAP-15765`, `PDIAP-15836`, and `PDIAP-15838`
+- Follow up on active tickets through `ai/work-items/`, especially `PDIAP-14859`, `PDIAP-15765`, `PDIAP-15836`, and `PDIAP-15838`
 - 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

ai/state/work-items.md

@@ -1,16 +1,25 @@
 # Active Work Items
 
-Use this file to keep current Jira-linked work visible across sessions.
+Use this file as the quick summary for active Jira-linked work.
 
-Update it only with explicit, project-relevant information that is useful for future standups, status updates, or debugging context.
+Detailed ticket memory now lives under `ai/work-items/`.
+
+Update the per-ticket files first when scope, status, sequencing, or communication framing changes materially.
 
 ## Current
 
-- `PDIAP-15765` - AO DOB field error not showing investigation
-  Current note: root cause was documented; the DOB validation issue was confirmed on TeenIdentityCheck for authenticated users, and Jeff approved moving the story to Done once the new sprint starts.
-
-- `PDIAP-15836` - Modernize dismissal delegate lifecycle sequencing for pure SwiftUI environment
-  Current note: story came out of the AccountLink root cause investigation and related root cause document update; it was sized at 8 points, aligned with epic `26Q2 - Updating XFlowSDK to Decouple and Fix ApexKit Dependencies (Split Part 2)`, is meant to cover SwiftUI dismissal sequencing validation, should come after `PDIAP-15838`, and should use the same consumer-impact feature flag as the UIKit-removal rollout if possible.
+- `PDIAP-14859`
+  Detail: `ai/work-items/pdiap-14859.md`
+  Current note: active spike/planning work for the dual UIKit/SwiftUI path, dynamic `UIHostingController` removal, and consumer rollout planning.
 
 - `PDIAP-15838` - Remove Apollo for iOS
-  Current note: approved at 8 points; description and ACs were filled in and Jeff approved the scope to remove Apollo, GraphQL-specific networking code, related tests and mocks, and transport feature flags so REST remains. This is the next story to work on before `PDIAP-15836`.
+  Detail: `ai/work-items/pdiap-15838.md`
+  Current note: approved at `8` points and next to work on; keep it separate from the UIKit-removal spike.
+
+- `PDIAP-15836` - Modernize dismissal delegate lifecycle sequencing for pure SwiftUI environment
+  Detail: `ai/work-items/pdiap-15836.md`
+  Current note: approved at `8` points, rooted in the AccountLink dismissal sequencing investigation, and sequenced after `PDIAP-15838`.
+
+- `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.

ai/work-items/README.md

@@ -0,0 +1,25 @@
+# Work Items
+
+## Goal
+
+Keep active Jira-linked work in one canonical place so standups, manager updates, and memory syncs can reference each ticket precisely.
+
+---
+
+## Structure
+
+- `index.md`
+  Active index and quick status view.
+
+- `<jira-id>.md`
+  Canonical file for a specific ticket.
+
+---
+
+## Update Rules
+
+- Use one file per active or recently relevant Jira item.
+- Keep titles exact when approved or explicitly confirmed.
+- If the title is not confirmed, store the Jira ID and current framing without inventing a final title.
+- Update the ticket file when scope, sequencing, points, status, rollout implications, or reproducibility meaningfully change.
+- Keep `ai/state/work-items.md` as a short bridge summary, not the primary source of detailed ticket context.

ai/work-items/index.md

@@ -0,0 +1,31 @@
+# Work Item Index
+
+## Goal
+
+Provide a quick view of active and recently relevant Jira-linked work while keeping the full detail in one file per ticket.
+
+---
+
+## Active
+
+- [pdiap-14859.md](./pdiap-14859.md)
+  `PDIAP-14859` active spike/planning work around dual UIKit/SwiftUI support, dynamic `UIHostingController` removal, and consumer rollout planning.
+
+- [pdiap-15838.md](./pdiap-15838.md)
+  `PDIAP-15838` next story to work on; approved scope removes Apollo and GraphQL-specific iOS transport code while leaving REST.
+
+- [pdiap-15836.md](./pdiap-15836.md)
+  `PDIAP-15836` approved follow-up story for dismissal delegate lifecycle sequencing in pure SwiftUI; comes after `PDIAP-15838`.
+
+## Holding / Closure Pending
+
+- [pdiap-15765.md](./pdiap-15765.md)
+  `PDIAP-15765` authenticated-only TeenIdentityCheck DOB issue; root cause documented and waiting for the right closure timing.
+
+---
+
+## Usage
+
+- Read this file first for active ticket context.
+- Open the specific ticket file when you need exact scope, sequencing, or communication wording.
+- Update the per-ticket file first when ticket context changes materially.

ai/work-items/pdiap-14859.md

@@ -0,0 +1,40 @@
+# PDIAP-14859
+
+## Status
+
+- Active
+- Current focus on April 10, 2026
+
+---
+
+## Current Framing
+
+- This work is currently framed in the workspace as a dual UIKit/SwiftUI plan that removes `UIHostingController` dynamically while preserving both flows appropriately.
+- The remaining deliverable is process-oriented, not just technical implementation.
+
+---
+
+## Current Scope
+
+- 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`.
+- Include validation expectations in `XQ1`.
+- Include consumer communication expectations.
+- Include a 30-day production period with no reported bugs before final removal.
+- Include a follow-up release to remove the feature flag and old code after rollout confidence is achieved.
+
+---
+
+## Notes
+
+- The workspace does not currently hold an approved final title for this ticket beyond the Jira ID.
+- 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.
+
+---
+
+## Related Work
+
+- Related consumer rollout thinking should stay aligned with `PDIAP-15836`.
+- `PDIAP-15838` should not be framed as part of this UIKit-removal spike.

ai/work-items/pdiap-15765.md

@@ -0,0 +1,35 @@
+# PDIAP-15765 - AO DOB field error not showing investigation
+
+## Status
+
+- Holding
+- Ready for closure timing review
+
+---
+
+## Context
+
+- This ticket is tied to an AO DOB validation issue.
+- The issue was confirmed in the `TeenIdentityCheck` flow for authenticated users.
+
+---
+
+## Confirmed Findings
+
+- The issue reproduces only for authenticated users based on the currently stored evidence.
+- Root cause was documented.
+- The original external report was incomplete.
+
+---
+
+## Current Guidance
+
+- Treat the issue as scoped and understood unless new evidence appears.
+- 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.
+
+---
+
+## Next Step
+
+- Jeff approved moving the story to Done once the new sprint starts.

ai/work-items/pdiap-15836.md

@@ -0,0 +1,38 @@
+# PDIAP-15836 - Modernize dismissal delegate lifecycle sequencing for pure SwiftUI environment
+
+## Status
+
+- Approved
+- Sequenced after `PDIAP-15838`
+- Sized at `8` points
+
+---
+
+## Context
+
+- This story came out of the `AccountLink` root cause investigation.
+- It is tied to the dismissal sequencing problem found after UIKit removal in SwiftUI-only paths.
+- The root cause document was updated and the revised wording was approved.
+
+---
+
+## Approved Scope
+
+- Modernize dismissal delegate lifecycle sequencing for pure SwiftUI flows.
+- Cover the missing lifecycle contract where delegate callbacks can happen before the view is fully removed.
+- Validate the change across affected SwiftUI flows rather than only in one narrow reproduction.
+
+---
+
+## Sequencing And Dependencies
+
+- This story should come after `PDIAP-15838`.
+- It is aligned with epic `26Q2 - Updating XFlowSDK to Decouple and Fix ApexKit Dependencies (Split Part 2)`.
+- If possible, it should use the same consumer-impact feature flag strategy as the broader UIKit-removal rollout.
+
+---
+
+## Communication Notes
+
+- Keep the scope framed as lifecycle sequencing in a pure SwiftUI environment, not only as a symptom like multiple modal presentation.
+- If mentioned externally, keep it separate from `PDIAP-15838`.

ai/work-items/pdiap-15838.md

@@ -0,0 +1,37 @@
+# PDIAP-15838 - Remove Apollo for iOS
+
+## Status
+
+- Approved
+- Next story to work on
+- Sized at `8` points
+
+---
+
+## Context
+
+- This ticket covers the REST migration cleanup on iOS.
+- The approved title is `Remove Apollo for iOS`.
+
+---
+
+## Approved Scope
+
+- Remove Apollo from iOS.
+- Remove GraphQL-specific networking code.
+- Remove related tests and mocks.
+- Remove transport feature flags so REST remains.
+
+---
+
+## Current Guidance
+
+- Do not frame this ticket as directly tied to the UIKit-removal spike.
+- Do not imply it is dependent on or part of dismissal-sequencing work.
+- Keep the migration framing explicit: REST remains behind a feature flag until otherwise confirmed, and GraphQL fallback context still matters when describing the overall migration.
+
+---
+
+## Sequencing
+
+- This is the next story to work on before `PDIAP-15836`.