feat: Update behavior rules and documentation for workspace maintenance and flow references

ai/AGENTS.md

@@ -69,6 +69,7 @@ When drafting messages for a manager or stakeholder:
 - If the user asks for the latest/last/recent Mattermost message, the latest message from Jeff/current manager, or what someone just said, synchronize Mattermost first and then answer from the refreshed inbox
 - If automatic refresh is uncertain, use the explicit latest-message flow: run the Mattermost sync command, then answer from refreshed output only
 - Treat all meaningful user prompts as potential memory updates, not only explicit sync commands
+- Treat meaningful user corrections about workspace behavior as tool-maintenance inputs, not only as notes. If a correction affects a command, prompt, agent, skill, or knowledge rule, update that linked file directly.
 - If a Mattermost sync or other context-ingestion step fails, do not update `ai/logs/`, `ai/state/`, or stable context files based on that failure
 - Do not record missing dependencies, failed sync attempts, or missing inbox files as project facts unless the user explicitly asks to track the operational issue
 - Auto-promote Mattermost content when it is clearly project-relevant, explicit, and high-confidence
@@ -81,6 +82,7 @@ When drafting messages for a manager or stakeholder:
 - Maintain `ai/context/people/` when repeated names, roles, or stakeholder relationships become useful for future sessions
 - Update existing memory when the new information is a correction, clarification, or refinement of something already stored
 - Prefer updating stable project context over appending generic operational summaries
+- Do not leave reusable behavior rules only in daily logs. Promote them to the prompt, command, agent, skill, or process file that controls future behavior.
 - Do not create daily log entries for tooling activity, sync status, or generic chat noise
 - For Swift/iOS best-practice answers, distinguish current Apple guidance from project-safe recommendations when Fidelity constraints may change the answer
 - For Copilot prompts, include only relevant context, tell Copilot what to inspect, and state constraints, non-goals, expected output, and validation
@@ -93,6 +95,12 @@ When drafting messages for a manager or stakeholder:
   - `ai/context/people/index.md` for active roster mapping
   - `ai/context/people/<person>.md` for person-specific context
   - `ai/context/decisions/*.md` for confirmed decisions
+- If the new fact changes how this workspace should operate, update the linked tool surface as well:
+  - `.opencode/commands/*.md` for slash-command behavior
+  - `prompts/*.md` for reusable output templates
+  - `.opencode/agents/*.md` and `ai/AGENTS.md` for default agent behavior
+  - `.opencode/skills/*/SKILL.md` for specialized workflows
+  - `knowledge/*.md` or `ai/context/process/*.md` for durable process rules
 - Prefer updating stale context over leaving conflicting statements in different files
 - If context is still uncertain, record it in the daily log rather than promoting it to a stable context file
 

ai/context/index.md

@@ -38,6 +38,7 @@ Durable context about recurring streams of work and investigation:
 - [workstreams/xflow-debugging.md](./workstreams/xflow-debugging.md)
 - [workstreams/xflow-swiftui-migration.md](./workstreams/xflow-swiftui-migration.md)
 - [workstreams/consumer-integration.md](./workstreams/consumer-integration.md)
+- [workstreams/flow-page-references.md](./workstreams/flow-page-references.md)
 
 ### `process/`
 

ai/context/process/communication.md

@@ -24,6 +24,8 @@ When the format fits, prefer:
 - For standups, report the previous workday context, not blindly the prior calendar day.
 - On Mondays, use Friday's work context unless a later prior day has Mattermost activity.
 - If the previous calendar day has no project activity because of weekend, holiday, or OOO, use the latest prior day with Mattermost activity.
+- For standups, when a Jira item has multiple concrete updates, use one top-level `JIRA-ID - Title` bullet and indented markdown sub-bullets instead of repeating the same Jira line.
+- When a flow/page shorthand could be ambiguous, prefer the real flow identifier and page name from `ai/context/workstreams/flow-page-references.md`.
 - Avoid vague phrasing such as:
   - "same behavior"
   - "looks fixed"

ai/context/process/context-maintenance.md

@@ -17,6 +17,7 @@ Keep this workspace useful as living memory instead of a pile of disconnected no
   - `ai/state/work-items.md` for the compact active-work summary
   - `ai/context/` for durable project knowledge
   - `ai/context/people/` for named person context
+  - `.opencode/commands/`, `prompts/`, `.opencode/agents/`, `.opencode/skills/`, or `knowledge/` for reusable behavior rules that control how the workspace responds
 
 ---
 
@@ -26,9 +27,11 @@ Keep this workspace useful as living memory instead of a pile of disconnected no
 - Do not promote failed syncs or tooling errors as project facts.
 - Promote repeated durable patterns from historical archives into stable context when confidence is high.
 - Keep old status-only details archive-only unless they still change current understanding.
+- Treat user corrections about command output, prompt structure, memory handling, or agent behavior as inputs to the operational surface, not just as daily notes.
 
 ---
 
 ## Curation Rule
 
 - If a new stable context file is added, keep `project.md` and `index.md` aligned so future sessions can discover it quickly.
+- If a new rule affects a slash command or reusable prompt, update that command or prompt directly so the behavior changes on the next run.

ai/context/workstreams/flow-page-references.md

@@ -0,0 +1,25 @@
+# Flow And Page References
+
+## Goal
+
+Keep recurring flow names, page names, and shorthand references aligned so debugging notes and external updates do not drift into ambiguous wording.
+
+---
+
+## Current Mappings
+
+- `HybridYouthAccountOpening`
+  - This is the real flow identifier when David refers to the Youth flow in recent AO validation discussions.
+  - The relevant page in this flow is `TeenIdentityCheck`.
+
+- `HybridBrokerageAccountOpening`
+  - This is the separate authenticated flow discussed alongside the Youth issue.
+  - The relevant page in this flow is `JointIdentityCheck`.
+
+---
+
+## Usage
+
+- When drafting updates, prefer the real flow identifier if there is any risk that shorthand like `Youth flow` or `HybridBrokerage` could be misunderstood.
+- When a shorthand is still useful for readability, keep the real flow ID available somewhere in the same session context.
+- Capture additional stable flow/page mappings here when they come up repeatedly in debugging, standups, Jira comments, or consumer communication.

ai/context/workstreams/index.md

@@ -17,6 +17,9 @@
 - [consumer-integration.md](./consumer-integration.md)
   Release and validation coupling across XFlow, XFlowViewMaker, FT modules, and Fid4.
 
+- [flow-page-references.md](./flow-page-references.md)
+  Stable mapping between shorthand flow references and their real flow/page identifiers.
+
 ---
 
 ## Guidance

ai/logs/2026-04-15.md

@@ -40,3 +40,10 @@
 - The April 15 iOS fix PR is a one-line change in `XFlowViewAdapterRepresentable.swift` for `.apxDateSelect`, adding `birthDate` as a fallback after `validations`.
 - This PR should be described as a small compatibility bug fix for older AO-style payloads rather than as a broader Android-parity refactor.
 - David opened the PR for this minimal iOS compatibility fix.
+
+## Standup And Flow Naming Notes
+
+- David prefers standups to use one top-level Jira bullet with indented sub-bullets when a single ticket has multiple updates.
+- In recent standup wording, `Youth flow` should be treated as shorthand for the real flow ID `HybridYouthAccountOpening`.
+- The relevant page in that flow is `TeenIdentityCheck`.
+- The separate authenticated flow under discussion remains `HybridBrokerageAccountOpening`, with the relevant page `JointIdentityCheck`.

ai/state/current.md

@@ -9,8 +9,8 @@
 - Follow up on active tickets through `ai/work-items/`, especially `PDIAP-14859`, `PDIAP-15765`, `PDIAP-15836`, and `PDIAP-15838`
 - Wrap up `PDIAP-14859` by publishing the approved rollout document, linking the spike-result documents and follow-up story, then closing the spike
 - After the immediate `PDIAP-14859` closeout and `PDIAP-15765` resume work, return to `PDIAP-15838`; `PDIAP-15836` comes later
-- Resume `PDIAP-15765` for the authenticated iOS-only Youth `TeenIdentityCheck` handling gap so iOS aligns with Android behavior
-- Keep the separate `HybridBrokerage` scenario out of `PDIAP-15765` scope unless later evidence proves it belongs there
+- Resume `PDIAP-15765` for the authenticated iOS-only `HybridYouthAccountOpening` / `TeenIdentityCheck` handling gap so iOS aligns with Android behavior
+- Keep the separate `HybridBrokerageAccountOpening` / `JointIdentityCheck` scenario out of `PDIAP-15765` scope unless later evidence proves it belongs there
 - 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
@@ -20,7 +20,8 @@
 - 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 uses a global feature-flag rollout model with broad XQ1 validation before production enablement
 - The rollout document should use the new flag name `xflow-swiftui-container-enabled` and note that the flag will be added later during implementation
-- 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
+- Re-check the authenticated AO validation issue with scenario-specific evidence: the `HybridYouthAccountOpening` / `TeenIdentityCheck` path currently points to an iOS-only decoding gap, while a separate `HybridBrokerageAccountOpening` / `JointIdentityCheck` case reproduces on both platforms
+- The immediate Youth issue appears fixed on the service side after the payload moved from `birthDate` to `validations`, but the XFlowSDK-side fallback PR should still ship in the next release
 
 ---
 
@@ -49,6 +50,7 @@
 - Standups should prefer updates directly tied to active work items over one-off memory refreshes or side questions
 - Standups should include story titles whenever a reported update maps to a Jira item
 - Standups should use bullet points for each item, but avoid dash-separated title formatting inside the sentence body
+- When one Jira item has multiple concrete updates, prefer one top-level Jira bullet with indented sub-bullets rather than repeating the same Jira line multiple times
 - When pairing a Jira ID with a title in standups, prefer a simple hyphen after the ID or omit punctuation instead of using commas
 - Standups should omit side questions or manager-only context refreshes unless they materially changed story work
 - If a root cause document or other documentation update directly supports a story, it should be reported under that story instead of as a separate standalone item

ai/state/work-items.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: move the story back to In Progress for the authenticated iOS-only Youth `TeenIdentityCheck` handling gap, while keeping the separate cross-platform `HybridBrokerage` case out of scope for this fix.
+  Current note: a small XFlowSDK PR is open for the iOS `birthDate` fallback, the immediate `HybridYouthAccountOpening` / `TeenIdentityCheck` issue appears fixed on the service side, and the separate cross-platform `HybridBrokerageAccountOpening` / `JointIdentityCheck` case remains out of scope for this fix.

ai/work-items/index.md

@@ -20,7 +20,7 @@ Provide a quick view of active and recently relevant Jira-linked work while keep
 ## Active / Reopened
 
 - [pdiap-15765.md](./pdiap-15765.md)
-  `PDIAP-15765` authenticated-only TeenIdentityCheck DOB issue; reopened around the iOS-only Youth-flow handling gap while the separate cross-platform `HybridBrokerage` scenario stays out of scope.
+  `PDIAP-15765` authenticated-only DOB issue in `HybridYouthAccountOpening` / `TeenIdentityCheck`; reopened around the iOS-only handling gap while the separate cross-platform `HybridBrokerageAccountOpening` / `JointIdentityCheck` scenario stays out of scope.
 
 ---
 

ai/work-items/pdiap-15765.md

@@ -4,13 +4,14 @@
 
 - Active again
 - Move back to In Progress on the next workday
+- Small XFlowSDK compatibility PR opened for the iOS-side fix
 
 ---
 
 ## Context
 
 - This ticket is tied to an AO DOB validation issue.
-- The issue was confirmed in the `TeenIdentityCheck` flow for authenticated users.
+- The issue was confirmed for authenticated users in the `HybridYouthAccountOpening` flow on the `TeenIdentityCheck` page.
 
 ---
 
@@ -21,23 +22,28 @@
 - 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.
+- A `HybridBrokerageAccountOpening` / `JointIdentityCheck` scenario reproduces on both iOS and Android.
+- A `HybridYouthAccountOpening` / `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.
+- Later validation on April 15 showed the original `HybridYouthAccountOpening` / `TeenIdentityCheck` issue no longer reproduces once the payload uses `validations` instead of `birthDate`.
+- A minimal XFlowSDK fix was still prepared on April 15 so the iOS `.apxDateSelect` path also falls back to `birthDate` for a future release.
 
 ---
 
 ## Current Guidance
 
-- 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.
+- Treat the iOS-only `HybridYouthAccountOpening` / `TeenIdentityCheck` discrepancy as the main client-side issue currently aligned with the story.
+- Keep the cross-platform `HybridBrokerageAccountOpening` / `JointIdentityCheck` 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.
+- The originally reported Youth issue appears fixed immediately by the service-side payload update, but the XFlowSDK fallback PR should still be released so iOS handles the older `birthDate` format more safely.
+- The `HybridBrokerageAccountOpening` / `JointIdentityCheck` issue is different from the original Youth report: the rule content itself does not include `ageRange` or `eighteenOrAbove`, so that path still points to a service-side update rather than the same iOS parsing gap.
 
 ---
 
 ## Next Step
 
-- Resume the story and implement the iOS-side handling so the authenticated Youth `TeenIdentityCheck` service response is handled the same way as Android.
-- Keep the separate `HybridBrokerage` scenario out of the client-fix scope unless later evidence proves it is part of the same issue.
-- Consider a separate follow-up ticket for the cross-platform service-side issue if that path still stands after the iOS-only fix is underway.
+- Get the small XFlowSDK compatibility PR reviewed and released.
+- Close the story with comments explaining that the immediate Youth issue was resolved on the service side and that the XFlowSDK fallback fix will be available in the next release.
+- Keep the separate `HybridBrokerageAccountOpening` / `JointIdentityCheck` scenario out of the client-fix scope unless later evidence proves it is part of the same issue.
+- Consider a separate follow-up ticket for the cross-platform service-side issue if that path still stands after consumer confirmation.