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

.opencode/agents/fidelity.md

@@ -18,7 +18,8 @@ Behavior rules:
 - Promote information carefully:
   - daily facts go to `ai/logs/YYYY-MM-DD.md`
   - current priorities go to `ai/state/current.md`
-  - active Jira-linked work goes to `ai/state/work-items.md`
+  - active Jira-linked work goes to `ai/work-items/*.md`
+  - the active-work summary goes to `ai/state/work-items.md`
   - durable project knowledge overview goes to `ai/context/project.md`
   - system-specific durable knowledge goes to `ai/context/systems/`
   - workstream-specific durable knowledge goes to `ai/context/workstreams/`

.opencode/commands/fidelity-context.md

@@ -16,6 +16,7 @@ Use these files as the baseline context:
 @ai/context/process/jira-story-rules.md
 @ai/context/people/manager.md
 @ai/context/people/index.md
+@ai/work-items/index.md
 @ai/state/current.md
 @ai/state/work-items.md
 @ai/context/decisions/rest-vs-graphql.md
@@ -37,6 +38,10 @@ Recent logs available:
 
 !`ls -1 ai/logs 2>/dev/null | sort | tail -n 5`
 
+Detailed active work item files, if available:
+
+!`if [ -d ai/work-items ]; then for f in ai/work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; else echo "No work item files available."; fi`
+
 Latest Mattermost context, if available:
 
 !`if [ -s ai/inbox/mattermost-latest.md ]; then cat ai/inbox/mattermost-latest.md; elif [ -s scripts/mattermost/generated/mattermost_context.jsonl ]; then cat scripts/mattermost/generated/mattermost_context.jsonl; else echo "No Mattermost context available."; fi`

.opencode/commands/log-note.md

@@ -12,6 +12,7 @@ Read:
 @ai/context/project.md
 @ai/context/workstreams/index.md
 @ai/context/process/context-maintenance.md
+@ai/work-items/index.md
 @ai/state/current.md
 @ai/state/work-items.md
 @knowledge/agent-memory-rules.md

.opencode/commands/manager-update.md

@@ -14,6 +14,7 @@ Read:
 @ai/context/process/communication.md
 @ai/context/people/manager.md
 @ai/context/people/index.md
+@ai/work-items/index.md
 @ai/state/current.md
 @ai/state/work-items.md
 @knowledge/communication-rules.md
@@ -27,6 +28,10 @@ Latest Mattermost context, if available:
 
 !`if [ -s ai/inbox/mattermost-latest.md ]; then cat ai/inbox/mattermost-latest.md; elif [ -s scripts/mattermost/generated/mattermost_context.jsonl ]; then cat scripts/mattermost/generated/mattermost_context.jsonl; else echo "No Mattermost context available."; fi`
 
+Detailed active work item files, if available:
+
+!`if [ -d ai/work-items ]; then for f in ai/work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; else echo "No work item files available."; fi`
+
 User draft or rough notes:
 
 $ARGUMENTS

.opencode/commands/mattermost-sync.md

@@ -22,7 +22,8 @@ Then:
 - automatically promote explicit, project-relevant, high-confidence facts
 - default destination is `ai/logs/$(date +%F).md`
 - update `ai/state/current.md` only for facts that materially change the current work window
-- update `ai/state/work-items.md` for explicit Jira IDs, approved titles, points, scope, and status notes
+- update `ai/work-items/*.md` for explicit Jira IDs, approved titles, points, scope, and status notes
+- keep `ai/state/work-items.md` aligned as the compact summary of active ticket files
 - do not write tooling noise, sync status, or generic chat chatter into project memory
 - if a fact is ambiguous, skip it rather than asking the user what to do
 

.opencode/commands/promote-project-context.md

@@ -12,6 +12,7 @@ Read:
 @ai/context/systems/index.md
 @ai/context/workstreams/index.md
 @ai/context/process/index.md
+@ai/work-items/index.md
 @ai/state/current.md
 @ai/state/work-items.md
 @knowledge/workspace-model.md
@@ -41,6 +42,7 @@ Instructions:
 - Update the smallest correct set of files among:
   - `ai/logs/$(date +%F).md`
   - `ai/state/current.md`
+  - `ai/work-items/*.md`
   - `ai/state/work-items.md`
   - `ai/context/project.md`
   - `ai/context/systems/*.md`

.opencode/commands/slack-import.md

@@ -30,6 +30,7 @@ Read:
 @ai/context/process/index.md
 @ai/context/people/index.md
 @ai/context/people/manager.md
+@ai/work-items/index.md
 @ai/state/current.md
 @ai/state/work-items.md
 @knowledge/agent-memory-rules.md

.opencode/commands/standup.md

@@ -18,6 +18,7 @@ Read:
 @ai/context/process/communication.md
 @ai/context/process/jira-story-rules.md
 @ai/context/people/manager.md
+@ai/work-items/index.md
 @ai/state/current.md
 @ai/state/work-items.md
 @knowledge/communication-rules.md
@@ -35,6 +36,10 @@ Latest Mattermost context, preferring inbox and falling back to generated JSONL:
 
 !`if [ -s ai/inbox/mattermost-latest.md ]; then cat ai/inbox/mattermost-latest.md; elif [ -s scripts/mattermost/generated/mattermost_context.jsonl ]; then cat scripts/mattermost/generated/mattermost_context.jsonl; else echo "No Mattermost context available."; fi`
 
+Detailed active work item files, if available:
+
+!`if [ -d ai/work-items ]; then for f in ai/work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; else echo "No work item files available."; fi`
+
 Before drafting:
 
 - update workspace memory if the refreshed context introduced clear high-confidence project facts

.opencode/commands/story-draft.md

@@ -27,6 +27,7 @@ Read:
 @ai/context/process/jira-story-rules.md
 @ai/context/people/manager.md
 @ai/context/people/index.md
+@ai/work-items/index.md
 @ai/state/current.md
 @ai/state/work-items.md
 @knowledge/communication-rules.md
@@ -40,6 +41,10 @@ Latest Mattermost context, if available:
 
 !`if [ -s ai/inbox/mattermost-latest.md ]; then cat ai/inbox/mattermost-latest.md; elif [ -s scripts/mattermost/generated/mattermost_context.jsonl ]; then cat scripts/mattermost/generated/mattermost_context.jsonl; else echo "No Mattermost context available."; fi`
 
+Detailed active work item files, if available:
+
+!`if [ -d ai/work-items ]; then for f in ai/work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; else echo "No work item files available."; fi`
+
 Requirements:
 
 - Preserve the exact technical meaning of the input

.opencode/commands/sync-context.md

@@ -15,6 +15,7 @@ Read:
 @ai/context/process/context-maintenance.md
 @ai/context/people/manager.md
 @ai/context/people/index.md
+@ai/work-items/index.md
 @ai/state/current.md
 @ai/state/work-items.md
 @knowledge/workspace-model.md
@@ -35,6 +36,7 @@ Instructions:
 - Decide whether the new information belongs in:
   - today's log
   - `ai/state/current.md`
+  - `ai/work-items/*.md`
   - `ai/state/work-items.md`
   - `ai/context/project.md`
   - `ai/context/systems/`

.opencode/plugins/fidelity-compaction.js

@@ -21,6 +21,7 @@ export const FidelityCompaction = async ({ directory }) => {
         "ai/context/process/communication.md",
         "ai/context/people/manager.md",
         "ai/context/people/index.md",
+        "ai/work-items/index.md",
         "ai/state/current.md",
         "ai/state/work-items.md",
         "ai/context/decisions/rest-vs-graphql.md",

AGENTS.md

@@ -21,6 +21,7 @@ The detailed operating rules live in:
 - `ai/context/process/communication.md`
 - `ai/context/people/manager.md`
 - `ai/context/people/index.md`
+- `ai/work-items/index.md`
 - `ai/state/current.md`
 - `ai/state/work-items.md`
 - `knowledge/workspace-model.md`
@@ -39,7 +40,7 @@ These are also loaded through `opencode.json`.
 - `mattermost-sync` should automatically promote high-confidence project facts without asking what to promote.
 - Prefer `ai/logs/` as the default destination for new Mattermost-derived facts.
 - Promote to `ai/state/current.md` only when the fact materially changes active work over the next few days.
-- Keep explicit Jira IDs and approved titles in `ai/state/work-items.md` when they are useful for future standups or manager updates.
+- Keep explicit Jira IDs and approved titles visible in `ai/work-items/` and summarize active items in `ai/state/work-items.md` when they are useful for future standups or manager updates.
 - Promote to `ai/context/project.md` only when the fact changes durable project understanding.
 - When a repeatedly mentioned person becomes relevant to project flow, create or update a file under `ai/context/people/`.
 - Keep role-to-person mapping explicit in `ai/context/people/manager.md` and the roster in `ai/context/people/index.md`.

README.md

@@ -53,6 +53,7 @@ Runtime context for AI support.
 
 - `AGENTS.md` -> behavior rules for AI agents
 - `context/` -> stable knowledge organized by systems, workstreams, process, people, and decisions
+- `work-items/` -> one file per active Jira-linked unit of work
 - `state/` -> current focus, active issues, and communication needs
 - `logs/` -> daily work record
 
@@ -94,6 +95,7 @@ Helpers for future automation around context generation and communication drafti
 Read:
 
 - `ai/context/index.md`
+- `ai/work-items/index.md`
 - `ai/state/current.md`
 - `ai/context/project.md`
 - `ai/context/people/manager.md`

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
+- `PDIAP-14859`
-  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.
+  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-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-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`.

knowledge/agent-memory-rules.md

@@ -80,16 +80,18 @@ Use when the fact changes the active work window, including:
 - current blockers or debugging constraints
 - manager direction that changes the next few days of work
 
-### `ai/state/work-items.md`
+### `ai/work-items/*.md` and `ai/state/work-items.md`
 
-Use for current Jira-linked work that should remain easy to reference across sessions, especially:
+Use `ai/work-items/*.md` as the canonical memory for current Jira-linked work that should remain easy to reference across sessions, especially:
 
 - Jira IDs
 - approved or explicit titles
 - currently relevant status notes
 - current points or scope notes
 
-This file should help standups and manager updates mention work items precisely.
+Use `ai/state/work-items.md` as the summary view of what is active now.
+
+These files should help standups and manager updates mention work items precisely.
 
 ### `ai/context/project.md`
 

knowledge/memory-promotion-rules.md

@@ -41,9 +41,9 @@ Use current state only for facts that materially affect active work over the nex
 
 Do not copy every daily update into current state.
 
-### Promote to `ai/state/work-items.md`
+### Promote to `ai/work-items/*.md` and `ai/state/work-items.md`
 
-Use this file for:
+Use `ai/work-items/*.md` for:
 
 - explicit Jira IDs
 - approved or explicit story titles
@@ -53,6 +53,8 @@ Use this file for:
 
 If a Jira item is likely to appear again in standups or manager updates, it belongs here.
 
+Use `ai/state/work-items.md` as the compact summary of which ticket files are active.
+
 ### Promote to `ai/context/project.md`
 
 Use project context only for durable project knowledge that should survive beyond the current work window, such as:

opencode.json

@@ -49,6 +49,7 @@
     "./ai/context/process/jira-story-rules.md",
     "./ai/context/people/manager.md",
     "./ai/context/people/index.md",
+    "./ai/work-items/index.md",
     "./ai/state/current.md",
     "./ai/state/work-items.md",
     "./ai/context/decisions/rest-vs-graphql.md",

prompts/manager-update.md

@@ -1,6 +1,6 @@
 # Manager Update Prompt
 
-Use the current state, today's log, `ai/context/index.md`, `ai/context/process/communication.md`, `ai/context/people/manager.md`, and `ai/context/people/index.md`.
+Use the current state, today's log, `ai/work-items/index.md`, the relevant files under `ai/work-items/`, `ai/context/index.md`, `ai/context/process/communication.md`, `ai/context/people/manager.md`, and `ai/context/people/index.md`.
 
 Draft a Mattermost update for the current manager or stakeholder in concise, natural, professional US English.
 

prompts/standup.md

@@ -1,6 +1,6 @@
 # Standup Prompt
 
-Use `ai/state/current.md`, `ai/state/work-items.md`, `ai/context/index.md`, `ai/context/project.md`, `ai/context/workstreams/index.md`, `ai/context/process/communication.md`, `ai/context/people/manager.md`, yesterday's log, today's log if present, and the latest available Mattermost context.
+Use `ai/state/current.md`, `ai/work-items/index.md`, the relevant files under `ai/work-items/`, `ai/state/work-items.md`, `ai/context/index.md`, `ai/context/project.md`, `ai/context/workstreams/index.md`, `ai/context/process/communication.md`, `ai/context/people/manager.md`, yesterday's log, today's log if present, and the latest available Mattermost context.
 
 Generate a standup update for an iOS engineer working on Fidelity.