feat: Organize context files and enhance documentation for clarity and structure

2026-04-10 08:57:00 -06:00
parent 26f54ed302
commit ae9e69bd4b
38 changed files with 620 additions and 71 deletions
--- a/.opencode/agents/fidelity.md
+++ b/.opencode/agents/fidelity.md
@@ -19,7 +19,10 @@ Behavior rules:
  - 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`
-  - durable project knowledge goes to `ai/context/project.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/`
+  - process-specific durable knowledge goes to `ai/context/process/`
  - confirmed team or manager communication preferences go to `ai/context/people/manager.md`
  - role-to-person mapping and recurring stakeholders go to `ai/context/people/`
  - confirmed decisions go to `ai/context/decisions/`
--- a/.opencode/commands/fidelity-context.md
+++ b/.opencode/commands/fidelity-context.md
@@ -8,7 +8,12 @@ Use these files as the baseline context:

@README.md
@ai/AGENTS.md
+@ai/context/index.md
@ai/context/project.md
+@ai/context/systems/index.md
+@ai/context/workstreams/index.md
+@ai/context/process/communication.md
+@ai/context/process/jira-story-rules.md
@ai/context/people/manager.md
@ai/context/people/index.md
@ai/state/current.md
--- a/.opencode/commands/log-note.md
+++ b/.opencode/commands/log-note.md
@@ -8,7 +8,10 @@ Read:

@README.md
@ai/AGENTS.md
+@ai/context/index.md
@ai/context/project.md
+@ai/context/workstreams/index.md
+@ai/context/process/context-maintenance.md
@ai/state/current.md
@ai/state/work-items.md
@knowledge/agent-memory-rules.md
@@ -30,6 +33,7 @@ Instructions:
 - Keep the log concise but reusable for later standups and manager updates
 - If the notes are ambiguous, normalize them without inventing facts
 - If a note clearly corrects or sharpens existing current memory, update the corresponding canonical file as well
+- If a note reveals durable system, workstream, process, or people context, update the relevant canonical file instead of only appending to the log
 - Prefer `sync-context` for broader memory updates; use this command for fast daily capture

 After editing, respond with:
--- a/.opencode/commands/manager-update.md
+++ b/.opencode/commands/manager-update.md
@@ -8,9 +8,11 @@ Read:

@prompts/manager-update.md
@ai/AGENTS.md
+@ai/context/index.md
@ai/context/project.md
+@ai/context/workstreams/index.md
+@ai/context/process/communication.md
@ai/context/people/manager.md
-@ai/context/people/jeff-dewitte.md
@ai/context/people/index.md
@ai/state/current.md
@ai/state/work-items.md
--- a/.opencode/commands/promote-project-context.md
+++ b/.opencode/commands/promote-project-context.md
@@ -7,7 +7,11 @@ Use this only when you want an explicit manual promotion pass.
 Read:

@ai/AGENTS.md
+@ai/context/index.md
@ai/context/project.md
+@ai/context/systems/index.md
+@ai/context/workstreams/index.md
+@ai/context/process/index.md
@ai/state/current.md
@ai/state/work-items.md
@knowledge/workspace-model.md
@@ -39,6 +43,9 @@ Instructions:
  - `ai/state/current.md`
  - `ai/state/work-items.md`
  - `ai/context/project.md`
+  - `ai/context/systems/*.md`
+  - `ai/context/workstreams/*.md`
+  - `ai/context/process/*.md`
  - `ai/context/decisions/*.md`
 - Prefer concrete project updates over broad summaries
 - If a fact is still ambiguous, do not promote it
--- a/.opencode/commands/slack-import.md
+++ b/.opencode/commands/slack-import.md
@@ -23,7 +23,11 @@ First, run the importer:
 Read:

@ai/AGENTS.md
+@ai/context/index.md
@ai/context/project.md
+@ai/context/systems/index.md
+@ai/context/workstreams/index.md
+@ai/context/process/index.md
@ai/context/people/index.md
@ai/context/people/manager.md
@ai/state/current.md
--- a/.opencode/commands/standup.md
+++ b/.opencode/commands/standup.md
@@ -12,9 +12,12 @@ Read:

@prompts/standup.md
@ai/AGENTS.md
+@ai/context/index.md
@ai/context/project.md
+@ai/context/workstreams/index.md
+@ai/context/process/communication.md
+@ai/context/process/jira-story-rules.md
@ai/context/people/manager.md
-@ai/context/people/jeff-dewitte.md
@ai/state/current.md
@ai/state/work-items.md
@knowledge/communication-rules.md
--- a/.opencode/commands/story-draft.md
+++ b/.opencode/commands/story-draft.md
@@ -10,7 +10,7 @@ This command should optimize for:
 - explicit scope
 - useful acceptance criteria
 - clear ownership framing
- natural US English that Jeff can reuse or forward without rewriting
+- natural US English that the current manager or stakeholder can reuse or forward without rewriting

 Input notes or rough idea:

@@ -20,9 +20,12 @@ Read:

@prompts/story-draft.md
@ai/AGENTS.md
+@ai/context/index.md
@ai/context/project.md
+@ai/context/workstreams/index.md
+@ai/context/process/communication.md
+@ai/context/process/jira-story-rules.md
@ai/context/people/manager.md
-@ai/context/people/jeff-dewitte.md
@ai/context/people/index.md
@ai/state/current.md
@ai/state/work-items.md
@@ -50,6 +53,7 @@ Requirements:
 - Acceptance criteria should be testable and scoped to the proposed story
 - If the story looks too large or too ambiguous, say so explicitly and suggest spike framing instead
 - If useful, include a short note about dependencies, blockers, or coordination needed
+- If the story touches consumer validation or release propagation, reflect that explicitly in the description or notes

 Return:

--- a/.opencode/commands/sync-context.md
+++ b/.opencode/commands/sync-context.md
@@ -8,7 +8,11 @@ Read:

@README.md
@ai/AGENTS.md
+@ai/context/index.md
@ai/context/project.md
+@ai/context/systems/index.md
+@ai/context/workstreams/index.md
+@ai/context/process/context-maintenance.md
@ai/context/people/manager.md
@ai/context/people/index.md
@ai/state/current.md
@@ -33,6 +37,9 @@ Instructions:
  - `ai/state/current.md`
  - `ai/state/work-items.md`
  - `ai/context/project.md`
+  - `ai/context/systems/`
+  - `ai/context/workstreams/`
+  - `ai/context/process/`
  - `ai/context/people/manager.md`
  - `ai/context/people/index.md`
  - `ai/context/people/*.md`
--- a/.opencode/commands/translate.md
+++ b/.opencode/commands/translate.md
@@ -15,7 +15,9 @@ Read:

@prompts/mattermost-translation.md
@ai/AGENTS.md
+@ai/context/index.md
@ai/context/project.md
+@ai/context/process/communication.md
@ai/context/people/manager.md
@ai/context/people/index.md
@knowledge/communication-rules.md
--- a/.opencode/plugins/fidelity-compaction.js
+++ b/.opencode/plugins/fidelity-compaction.js
@@ -14,7 +14,11 @@ export const FidelityCompaction = async ({ directory }) => {
    "experimental.session.compacting": async (_input, output) => {
      const baseFiles = [
        "README.md",
+        "ai/context/index.md",
        "ai/context/project.md",
+        "ai/context/systems/index.md",
+        "ai/context/workstreams/index.md",
+        "ai/context/process/communication.md",
        "ai/context/people/manager.md",
        "ai/context/people/index.md",
        "ai/state/current.md",
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -14,7 +14,11 @@ OpenCode should treat this project as a persistent context layer used to:
 The detailed operating rules live in:

 - `ai/AGENTS.md`
+- `ai/context/index.md`
 - `ai/context/project.md`
+- `ai/context/systems/index.md`
+- `ai/context/workstreams/index.md`
+- `ai/context/process/communication.md`
 - `ai/context/people/manager.md`
 - `ai/context/people/index.md`
 - `ai/state/current.md`
@@ -47,6 +51,7 @@ These are also loaded through `opencode.json`.
 - If a previous context file is now stale or inaccurate, update that file directly.
 - Prefer correcting canonical context over appending contradictory notes.
 - Keep changes concise and auditable.
+- When the topic is architectural or historical, prefer updating the relevant file under `ai/context/systems/`, `ai/context/workstreams/`, or `ai/context/process/` instead of overloading `ai/context/project.md`.

 ## Communication

--- a/README.md
+++ b/README.md
@@ -52,7 +52,7 @@ Fidelity iOS ecosystem:
 Runtime context for AI support.

 - `AGENTS.md` -> behavior rules for AI agents
- `context/` -> stable knowledge about Fidelity and team communication
+- `context/` -> stable knowledge organized by systems, workstreams, process, people, and decisions
 - `state/` -> current focus, active issues, and communication needs
 - `logs/` -> daily work record

@@ -93,6 +93,7 @@ Helpers for future automation around context generation and communication drafti

 Read:

+- `ai/context/index.md`
 - `ai/state/current.md`
 - `ai/context/project.md`
 - `ai/context/people/manager.md`
--- a/ai/AGENTS.md
+++ b/ai/AGENTS.md
@@ -62,6 +62,7 @@ When drafting messages for a manager or stakeholder:

 - Treat workspace files as persistent memory, not just reference notes
 - Before answering prompts about current work, verify `ai/state/current.md` and the latest relevant log in `ai/logs/`
+- Before answering architecture, process, or historical questions, check the relevant file under `ai/context/systems/`, `ai/context/workstreams/`, or `ai/context/process/`
 - If `ai/inbox/mattermost-latest.md` exists, check it before answering prompts about current status, standups, or supervisor communication
 - Treat all meaningful user prompts as potential memory updates, not only explicit sync commands
 - 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
@@ -72,6 +73,7 @@ When drafting messages for a manager or stakeholder:
 - 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
 - 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
 - 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
--- a/ai/context/index.md
+++ b/ai/context/index.md
@@ -0,0 +1,60 @@
+# Context Index
+
+## Goal
+
+Keep stable Fidelity context organized by domain so the agent can load the right information quickly.
+
+---
+
+## Structure
+
+### `project.md`
+
+High-level overview of the workspace, current Fidelity scope, and where durable context lives.
+
+### `systems/`
+
+Stable context about core product components and how they relate:
+
+- [systems/fid4.md](./systems/fid4.md)
+- [systems/xflowsdk.md](./systems/xflowsdk.md)
+- [systems/xflowviewmaker.md](./systems/xflowviewmaker.md)
+- [systems/ftframeworks.md](./systems/ftframeworks.md)
+
+### `workstreams/`
+
+Durable context about recurring streams of work and investigation:
+
+- [workstreams/rest-migration.md](./workstreams/rest-migration.md)
+- [workstreams/ao-discourse.md](./workstreams/ao-discourse.md)
+- [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)
+
+### `process/`
+
+Rules and expectations for how work should be communicated and maintained:
+
+- [process/communication.md](./process/communication.md)
+- [process/jira-story-rules.md](./process/jira-story-rules.md)
+- [process/context-maintenance.md](./process/context-maintenance.md)
+
+### `people/`
+
+Named people, role mapping, and collaboration context:
+
+- [people/index.md](./people/index.md)
+- [people/manager.md](./people/manager.md)
+
+### `decisions/`
+
+Confirmed technical or product decisions with ongoing impact.
+
+---
+
+## Usage
+
+- Load `project.md` and this index first.
+- Open `systems/` when the question is about architecture, ownership, or integration.
+- Open `workstreams/` when the question is about current priorities, debugging themes, or historical project patterns.
+- Open `process/` when drafting messages, standups, Jira notes, or deciding how to update memory.
--- a/ai/context/process/communication.md
+++ b/ai/context/process/communication.md
@@ -0,0 +1,35 @@
+# Communication Rules
+
+## Goal
+
+Make technical communication precise enough for manager updates, Jira notes, standups, and cross-team messages.
+
+---
+
+## Required Structure
+
+When the format fits, prefer:
+
+1. Context
+2. Observation
+3. Action
+
+---
+
+## Fidelity-Specific Rules
+
+- Always clarify authenticated vs non-authenticated when behavior depends on it.
+- Always separate external issues from regressions.
+- Always state reproducibility and scope.
+- Avoid vague phrasing such as:
+  - "same behavior"
+  - "looks fixed"
+  - "working as expected"
+
+---
+
+## Historical Signals From Slack
+
+- Jeff repeatedly requested polished, explicit wording for PR descriptions, story descriptions, and cross-team messages.
+- Historical Slack threads show that message quality changed how quickly stories were approved or understood.
+- Explicit language mattered most when communicating root cause, ownership boundaries, or whether a report was a confirmed regression.
--- a/ai/context/process/context-maintenance.md
+++ b/ai/context/process/context-maintenance.md
@@ -0,0 +1,33 @@
+# Context Maintenance
+
+## Goal
+
+Keep this workspace useful as living memory instead of a pile of disconnected notes.
+
+---
+
+## Stable Rules
+
+- Update canonical context when a durable fact changes.
+- Prefer correcting stale context over appending contradictory notes.
+- 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/context/` for durable project knowledge
+  - `ai/context/people/` for named person context
+
+---
+
+## Ingestion Rules
+
+- Treat Mattermost, Slack history, and direct prompts as potential memory sources.
+- 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.
+
+---
+
+## Curation Rule
+
+- If a new stable context file is added, keep `project.md` and `index.md` aligned so future sessions can discover it quickly.
--- a/ai/context/process/index.md
+++ b/ai/context/process/index.md
@@ -0,0 +1,12 @@
+# Process Index
+
+## Stable Process Guides
+
+- [communication.md](./communication.md)
+  How to frame technical updates and external communication.
+
+- [jira-story-rules.md](./jira-story-rules.md)
+  How to create or reference stories with the right scope and precision.
+
+- [context-maintenance.md](./context-maintenance.md)
+  How this workspace should be kept current as living memory.
--- a/ai/context/process/jira-story-rules.md
+++ b/ai/context/process/jira-story-rules.md
@@ -0,0 +1,30 @@
+# Jira Story Rules
+
+## Goal
+
+Keep Jira updates precise enough that the story reflects the real problem and remains easy to reference later.
+
+---
+
+## Stable Rules
+
+- Preserve Jira ID and explicit title whenever available.
+- Prefer story wording that describes the real contract or behavior gap, not only the first symptom.
+- Include authenticated-state or environment qualifiers when they materially affect scope.
+- Validate consumer behavior before finalizing scope when the issue depends on Fid4 or flagship.
+
+---
+
+## Story-Creation Guidance
+
+- Create or refine the story after the reproduction path is understood well enough to avoid mis-scoping.
+- Include points and scope only after the work has been framed clearly.
+- If the issue crosses SDK, adapter, FT modules, and consumer app boundaries, the story should say so.
+- If a bug is external or not yet confirmed as regression, avoid writing the ticket as if the root cause is already proven.
+
+---
+
+## Historical Signals From Slack
+
+- Historical Slack threads repeatedly show Jeff refining titles and descriptions before stories were created or shared.
+- Several story discussions centered on making the wording reflect deeper SwiftUI, lifecycle, or integration issues rather than surface symptoms alone.
--- a/ai/context/project.md
+++ b/ai/context/project.md
@@ -17,81 +17,47 @@ The product work happens outside this repository, usually from another machine.

 ---

-## Current Priorities
+## Stable Context Map

-### REST migration
+- Core systems live under:
+  - `ai/context/systems/`
+- Durable workstreams live under:
+  - `ai/context/workstreams/`
+- Stable communication and maintenance rules live under:
+  - `ai/context/process/`
+- Named people and role mapping live under:
+  - `ai/context/people/`

- REST is behind a feature flag
- GraphQL is still the default fallback
- REST should never be assumed active unless confirmed
- Migration must preserve behavior while Apollo is deprecated safely
-
-### Discourse and AO issues
-
- External reports are often incomplete
- Many reported issues are not confirmed regressions
- Some issues reproduce only with authenticated users
-
-### Flow debugging
-
- XFlow behavior changes based on backend configuration
- Entry point affects what the user sees
- Authentication state affects reproducibility
-
-### Testing complexity
-
- Around 15 entry points have been identified at code level
- Not all entry points are reachable from visible UI
- Validation often requires exploratory testing
-
-## Historical Slack patterns
-
- XFlow SwiftUI migration discussions repeatedly covered Next-button visibility, markdown modal presentation, and custom nav pin/unpin behavior
- Some historical pipeline failures were traced to Apex/ApexKit or Swift preview macro support in the consuming pipeline, not just XFlow itself
- Jeff often requested explicit, polished wording for PR descriptions and cross-team messages
- Historical discussions also surfaced recurring uncertainty around XFlow ownership boundaries versus consumer-app responsibility
- Cross-team dependency issues sometimes involved security, token access, or external pipeline configuration rather than only iOS code changes
- Historical AO and consumer bugs often turned out to be service/configuration issues, incomplete reproduction reports, or consuming-app integration issues rather than XFlow regressions
- Historical integration work repeatedly involved XFlowViewMaker, FTBusiness, FTFrameworks, and Fid4 release/version coupling, especially when validating fixes in real consumer flows
+The Slack archive has already been curated into those files so the agent does not need to rediscover the same patterns from raw history every session.

 ---

-## How This Workspace Is Used
+## Current Priorities
+
+- REST migration is replacing GraphQL over time, but REST is still behind a feature flag
+- AO and Discourse issues require careful classification because many are incomplete, external, or auth-dependent
+- XFlow debugging remains dynamic because behavior changes by entry point, authentication state, backend configuration, and consumer integration
+- Consumer validation often depends on Fid4, FT modules, and version propagation, not just SDK behavior
+
+---
+
+## Workspace Use

 This machine is used to:

 - maintain current project context
 - record findings from work performed elsewhere
- capture Mattermost communication that changes understanding
+- capture communication that changes technical understanding
 - prepare polished updates for the current manager or stakeholder
 - generate standups with better context coverage

-This means logs must capture both technical findings and communication context.
+This means the context files should hold durable engineering knowledge, while `ai/logs/` and `ai/state/` hold the moving day-to-day view.

 ---

-## People Context
+## First Files To Read

- The current manager role is mapped in `ai/context/people/manager.md`
- The active people roster lives in `ai/context/people/index.md`
- Repeatedly relevant named people should have individual files under `ai/context/people/`
-
---
-
-## Communication Expectations
-
-All important updates should clarify:
-
- whether the flow is authenticated or non-authenticated
- whether the issue is reproducible
- whether the report is external behavior or regression
- whether behavior is present in main
- what action is needed next
-
-Avoid phrases that hide scope, such as:
-
- "same behavior"
- "looks fixed"
- "working as expected"
-
-Use explicit framing instead.
+- `ai/context/index.md`
+- `ai/context/workstreams/index.md`
+- `ai/context/process/communication.md`
+- `ai/context/people/index.md`
--- a/ai/context/systems/fid4.md
+++ b/ai/context/systems/fid4.md
@@ -0,0 +1,30 @@
+# Fid4
+
+## Role
+
+Fid4 is the main Fidelity consumer iOS app and the most important environment for validating real integration behavior.
+
+---
+
+## Durable Context
+
+- Fid4 is the newer flagship-style app and is heavily SwiftUI-based.
+- Validation in Fid4 often reveals issues that do not appear in XFlowSDK isolation or sample apps.
+- Historical Slack context shows that some tickets were incorrectly scoped until behavior was checked in Fid4 or flagship.
+- Real consumer testing in Fid4 matters for modal presentation, validation messaging, and backend-driven flow behavior.
+
+---
+
+## Validation Implications
+
+- If an issue depends on real flow behavior, do not assume XFlow-only validation is sufficient.
+- When a story touches presentation, entry points, or consumer behavior, check whether Fid4 is required to confirm scope.
+- Build or startup instability in Fid4 can slow validation and should be treated as a practical investigation constraint.
+
+---
+
+## Historical Signals From Slack
+
+- Fid4 was repeatedly referenced as the right place to verify SwiftUI/XFlow bugs before finalizing scope.
+- Historical work included modal-on-modal presentation issues, goal/date validation behavior, and consumer-facing eventing questions.
+- Some XFlow tickets needed rework because the original spike or story had not been validated in flagship/Fid4.
--- a/ai/context/systems/ftframeworks.md
+++ b/ai/context/systems/ftframeworks.md
@@ -0,0 +1,32 @@
+# FTFrameworks
+
+## Role
+
+FTFrameworks contains consumer-side feature modules such as FTAccountOpen, FTTransfer, and related libraries that mediate how XFlow changes reach Fid4.
+
+---
+
+## Durable Context
+
+- FTFrameworks is often part of the real validation and release chain, not just a downstream detail.
+- Historical Slack context shows pinned FT module versions repeatedly blocking adoption of newer XFlow or XFlowViewMaker changes in Fid4.
+- Changes to XFlow often needed corresponding FTAccountOpen or FTTransfer updates before end-to-end testing was realistic.
+
+---
+
+## Validation And Release Implications
+
+- If Fid4 does not reflect the expected XFlow fix, check FT module versions before concluding the SDK change failed.
+- Version movement can require a chain such as:
+  - XFlowSDK
+  - XFlowViewMaker
+  - FTAccountOpen / FTTransfer
+  - Fid4
+- Test failures or publishing issues in FT modules can delay consumer validation even when the core XFlow change is ready.
+
+---
+
+## Historical Signals From Slack
+
+- FTAccountOpen and FTTransfer were repeatedly mentioned in version bump and release coordination work.
+- Historical messages also tied FTFrameworks to FTAuth and MFA-related stories, showing that dependency understanding matters when sizing or scoping work.
--- a/ai/context/systems/index.md
+++ b/ai/context/systems/index.md
@@ -0,0 +1,23 @@
+# Systems Index
+
+## Core Components
+
+- [fid4.md](./fid4.md)
+  Consumer app and the most important real-world validation environment.
+
+- [xflowsdk.md](./xflowsdk.md)
+  Backend-driven flow engine and the center of most Fidelity behavior analysis.
+
+- [xflowviewmaker.md](./xflowviewmaker.md)
+  Adapter layer historically involved in version bumps, release coupling, and removal evaluation.
+
+- [ftframeworks.md](./ftframeworks.md)
+  Consumer-side feature modules that often mediate whether XFlow changes can be validated in Fid4.
+
+---
+
+## Guidance
+
+- Start with `xflowsdk.md` for backend-driven behavior questions.
+- Start with `fid4.md` or `ftframeworks.md` for consumer validation and release flow questions.
+- Open `xflowviewmaker.md` when the question involves version bumps, transitional architecture, or pipeline friction.
--- a/ai/context/systems/xflowsdk.md
+++ b/ai/context/systems/xflowsdk.md
@@ -0,0 +1,39 @@
+# XFlowSDK
+
+## Role
+
+XFlowSDK is the backend-driven UI engine that renders Fidelity flows from service-provided configuration.
+
+---
+
+## Durable Context
+
+- XFlow behavior depends on backend rules, entry point, and authentication state.
+- SwiftUI migration work introduced recurring behavior questions that were not just visual; many were contract or lifecycle issues.
+- Historical Slack patterns show recurring topics around:
+  - component type expansion in SwiftUI
+  - Next-button visibility rules
+  - markdown link handling and analytics
+  - modal presentation and dismissal sequencing
+  - consumer-vs-framework ownership boundaries
+
+---
+
+## Debugging Implications
+
+- Do not treat XFlow output as static UI; backend configuration can change the result.
+- When behavior differs across environments, check whether the issue is:
+  - service/configuration driven
+  - auth-state driven
+  - entry-point driven
+  - consumer-integration driven
+- Some apparent XFlow regressions historically turned out to be consumer, pipeline, or environment issues.
+
+---
+
+## Historical Signals From Slack
+
+- SwiftUI behavior repeatedly needed parity work beyond UIKit assumptions.
+- Next-button visibility logic required using the full set of service parameters, not only label text.
+- Modal, delegate, and lifecycle sequencing became recurring themes in pure SwiftUI environments.
+- XFlow work often had to be validated through consumer repositories, not only inside the SDK.
--- a/ai/context/systems/xflowviewmaker.md
+++ b/ai/context/systems/xflowviewmaker.md
@@ -0,0 +1,29 @@
+# XFlowViewMaker
+
+## Role
+
+XFlowViewMaker is the adapter layer between XFlowSDK and consuming app/framework integration. It is under evaluation for reduction or removal.
+
+---
+
+## Durable Context
+
+- Historical release work often required bumping XFlowViewMaker alongside XFlowSDK before consumer validation was possible.
+- XFlowViewMaker was a recurring source of coupling between XFlow changes and Fid4 or flagship rollout.
+- Historical Slack evidence shows that version bumps through XFlowViewMaker were often blocked by external pipeline or dependency issues rather than pure feature regressions.
+
+---
+
+## Integration Implications
+
+- When a fix exists in XFlowSDK but is not visible in consumer validation, check whether XFlowViewMaker or downstream pinned versions are blocking adoption.
+- If the issue involves version propagation into Fid4, treat XFlowViewMaker as part of the release path unless direct-consumption work has replaced it.
+- Questions about removing or collapsing the layer should be evaluated against current consumer integration patterns, not just local SDK behavior.
+
+---
+
+## Historical Signals From Slack
+
+- XFlowViewMaker version bumps into flagship frequently surfaced `PreviewMacros.SwiftUI`, Apex, or pipeline compatibility issues.
+- Historical context shows growing pressure to reduce XFlowViewMaker-specific indirection and move toward simpler consumer paths.
+- Slack history also shows that tutorials and release steps around XFlowViewMaker were easy to misunderstand, which made version propagation a repeated risk.
--- a/ai/context/workstreams/ao-discourse.md
+++ b/ai/context/workstreams/ao-discourse.md
@@ -0,0 +1,33 @@
+# AO And Discourse Issues
+
+## Goal
+
+Handle externally reported issues without misclassifying scope or over-claiming regression.
+
+---
+
+## Stable Patterns
+
+- AO and Discourse reports are often incomplete or partially reproducible.
+- External reports should be treated as external behavior until verified.
+- Many issues only reproduce with authenticated users or in consumer-specific contexts.
+- Some historical reports turned out to be service/configuration issues, environment issues, or existing behavior rather than new regressions.
+
+---
+
+## Investigation Rules
+
+- Always clarify:
+  - authenticated vs non-authenticated
+  - reproducibility
+  - entry point
+  - whether the issue exists in main
+  - whether the behavior is external, existing, or regression
+- Do not use vague comparison phrases like "same behavior" without scope.
+
+---
+
+## Historical Signals From Slack
+
+- Historical reports around button visibility, analytics, slot updates, and consumer validation repeatedly required deeper reproduction work before scoping a fix.
+- Slack history shows multiple examples where the original ticket or report was not enough to define the real root cause.
--- a/ai/context/workstreams/consumer-integration.md
+++ b/ai/context/workstreams/consumer-integration.md
@@ -0,0 +1,36 @@
+# Consumer Integration And Release
+
+## Goal
+
+Capture the durable release and validation path between XFlow changes and real consumer behavior.
+
+---
+
+## Stable Patterns
+
+- End-to-end validation often requires more than an SDK change.
+- Historical Slack evidence shows repeated coupling across:
+  - XFlowSDK
+  - XFlowViewMaker
+  - FTFrameworks modules
+  - Fid4 / flagship
+- Version pins, publishing delays, and consumer build issues can block validation even when the original code change is ready.
+
+---
+
+## Investigation Rules
+
+- Before concluding a fix is absent in Fid4, check whether the right version actually propagated downstream.
+- Separate these failure modes:
+  - SDK bug
+  - adapter/version propagation issue
+  - FT module publish/test issue
+  - consumer app setup or pipeline issue
+- Consumer validation constraints should shape story scope and estimates because they can dominate the real effort.
+
+---
+
+## Historical Signals From Slack
+
+- Version bump work repeatedly involved XFlowViewMaker, FTAccountOpen, and FTTransfer.
+- Some rollout problems involved Jenkins, Apex/ApexKit, preview macro compatibility, or secret/token access rather than the product behavior under investigation.
--- a/ai/context/workstreams/index.md
+++ b/ai/context/workstreams/index.md
@@ -0,0 +1,26 @@
+# Workstreams Index
+
+## Active Durable Workstreams
+
+- [rest-migration.md](./rest-migration.md)
+  GraphQL deprecation and REST rollout constraints.
+
+- [ao-discourse.md](./ao-discourse.md)
+  External issue intake, ambiguity, and authenticated-only reproduction patterns.
+
+- [xflow-debugging.md](./xflow-debugging.md)
+  How to reason about backend-driven flows and dynamic behavior.
+
+- [xflow-swiftui-migration.md](./xflow-swiftui-migration.md)
+  Historical SwiftUI transition themes that still shape XFlow work.
+
+- [consumer-integration.md](./consumer-integration.md)
+  Release and validation coupling across XFlow, XFlowViewMaker, FT modules, and Fid4.
+
+---
+
+## Guidance
+
+- Open `ao-discourse.md` before classifying external bug reports.
+- Open `xflow-debugging.md` for reproduction and investigation framing.
+- Open `consumer-integration.md` when the work depends on release propagation or validation in consumer apps.
--- a/ai/context/workstreams/rest-migration.md
+++ b/ai/context/workstreams/rest-migration.md
@@ -0,0 +1,32 @@
+# REST Migration
+
+## Goal
+
+Deprecate GraphQL and Apollo safely while preserving behavior through REST-backed flows.
+
+---
+
+## Stable Constraints
+
+- REST is behind a feature flag.
+- GraphQL remains the default fallback unless confirmed otherwise.
+- REST should never be assumed active by default.
+- Migration work must preserve behavior parity before removing Apollo-related code.
+
+---
+
+## What Matters In Practice
+
+- Validation must clarify whether the tested path is actually using REST or still falling back to GraphQL.
+- Story scope should distinguish:
+  - transport migration work
+  - feature-flag cleanup
+  - tests and mocks tied to Apollo/GraphQL
+- Communication should avoid implying the migration is complete before the fallback path is removed.
+
+---
+
+## Historical Signals From Slack
+
+- Historical Slack evidence around release and dependency work reinforces that transport or dependency changes often require consumer validation, not just local SDK changes.
+- Some dependency and pipeline issues complicated migration-related rollout even when the technical change itself was understood.
--- a/ai/context/workstreams/xflow-debugging.md
+++ b/ai/context/workstreams/xflow-debugging.md
@@ -0,0 +1,37 @@
+# XFlow Debugging
+
+## Goal
+
+Debug backend-driven flows without losing track of dynamic dependencies or misclassifying integration behavior.
+
+---
+
+## Stable Patterns
+
+- XFlow screens are backend-driven, so UI can change without local code changes.
+- Reproduction depends on:
+  - entry point
+  - authentication state
+  - backend configuration
+  - consumer integration path
+- Not all entry points are reachable from visible UI; some require exploratory validation.
+
+---
+
+## Investigation Rules
+
+- Confirm the entry point before comparing behavior.
+- Separate service-driven behavior from client regressions.
+- Confirm whether the issue reproduces in:
+  - sample app
+  - XFlow-only environment
+  - Fid4 / flagship
+  - authenticated vs non-authenticated state
+- If a fix appears correct in the SDK but not in consumer validation, inspect the release chain before reopening root cause assumptions.
+
+---
+
+## Historical Signals From Slack
+
+- Historical debugging covered Next-button visibility, markdown modal analytics, modal presentation, slot updates, and SwiftUI lifecycle behavior.
+- Multiple pipeline or dependency problems looked like XFlow issues until the build chain or consumer integration path was inspected more carefully.
--- a/ai/context/workstreams/xflow-swiftui-migration.md
+++ b/ai/context/workstreams/xflow-swiftui-migration.md
@@ -0,0 +1,35 @@
+# XFlow SwiftUI Migration
+
+## Goal
+
+Track the durable behavior patterns introduced while moving XFlow from older assumptions toward a more complete SwiftUI implementation.
+
+---
+
+## Stable Themes
+
+- SwiftUI migration was not just a UI rewrite; it exposed contract, lifecycle, and parity gaps.
+- Historical Slack evidence repeatedly referenced:
+  - component type expansion beyond simple string assumptions
+  - Next-button visibility rules driven by full service parameters
+  - markdown link handling and analytics integration
+  - navigation and modal behavior in pure SwiftUI environments
+  - dismissal delegate lifecycle sequencing
+
+---
+
+## What Matters Now
+
+- When a SwiftUI issue appears, check whether the missing behavior is:
+  - parity with UIKit behavior
+  - an incomplete service contract interpretation
+  - a lifecycle sequencing problem
+  - a consumer presentation constraint in Fid4
+- Do not assume a visual issue is only cosmetic; several historical SwiftUI bugs changed flow behavior materially.
+
+---
+
+## Historical Signals From Slack
+
+- Jeff and Norman repeatedly refined story titles and descriptions around SwiftUI architecture changes, showing that scope wording mattered because the work was often deeper than the first symptom.
+- Historical Slack context also shows that SwiftUI-specific work frequently required cross-team clarification when external dependencies or consumer environments behaved differently.
--- a/ai/logs/2026-04-10.md
+++ b/ai/logs/2026-04-10.md
@@ -10,3 +10,4 @@
 - Use the approved title `Remove Apollo for iOS` for `PDIAP-15838`.
 - When a documentation or root cause update directly supports a story, report it under that story instead of as a separate standup item.
 - In standups, format Jira references as `ID - Title` or `ID Title`, not `ID, Title`.
+- Jeff clarified that `PDIAP-15838` is the next story to work on and `PDIAP-15836` comes later.
--- a/ai/state/current.md
+++ b/ai/state/current.md
@@ -8,6 +8,7 @@
 - Prepare better updates for the current manager or stakeholder through Mattermost
 - Follow up on `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

 ---

--- a/ai/state/work-items.md
+++ b/ai/state/work-items.md
@@ -10,7 +10,7 @@ Update it only with explicit, project-relevant information that is useful for fu
  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)`, and is meant to cover SwiftUI dismissal sequencing validation.
+  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, and should come after `PDIAP-15838`.

 - `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.
+  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`.
--- a/opencode.json
+++ b/opencode.json
@@ -41,7 +41,12 @@
  },
  "instructions": [
    "./README.md",
+    "./ai/context/index.md",
    "./ai/context/project.md",
+    "./ai/context/systems/index.md",
+    "./ai/context/workstreams/index.md",
+    "./ai/context/process/communication.md",
+    "./ai/context/process/jira-story-rules.md",
    "./ai/context/people/manager.md",
    "./ai/context/people/index.md",
    "./ai/state/current.md",
--- a/prompts/manager-update.md
+++ b/prompts/manager-update.md
@@ -1,6 +1,6 @@
 # Manager Update Prompt

-Use the current state, today's log, `ai/context/people/manager.md`, and `ai/context/people/jeff-dewitte.md`.
+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`.

 Draft a Mattermost update for the current manager or stakeholder in concise, natural, professional US English.

--- a/prompts/standup.md
+++ b/prompts/standup.md
@@ -1,6 +1,6 @@
 # Standup Prompt

-Use `ai/state/current.md`, `ai/state/work-items.md`, `ai/context/project.md`, `ai/context/people/manager.md`, `ai/context/people/jeff-dewitte.md`, yesterday's log, today's log if present, and the latest available Mattermost context.
+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.

 Generate a standup update for an iOS engineer working on Fidelity.

--- a/workflows/opencode-entry.md
+++ b/workflows/opencode-entry.md
@@ -31,6 +31,7 @@ Use OpenCode as the daily AI entry point for this workspace without losing proje
 - Project instructions load automatically from `opencode.json`.
 - Root rules also load automatically from `AGENTS.md`.
 - The main context command reads the stable workspace files plus today's log.
+- Stable context is split by systems, workstreams, process, people, and decisions so the agent can pull the right layer instead of overloading one project file.
 - Mattermost context can be refreshed into `ai/inbox/` using your existing local sync script.
 - Direct prompts are also treated as memory opportunities, so the agent can update workspace context during normal conversation.
 - Daily updates go back into the workspace, so later prompts inherit better context.