SRS: UC_8.2.9 — Flow 15: Pod Re-Assignment & Management

---

1. UC Index

---

UC_8.2.9 — Flow 15: Pod Re-Assignment & Management

---

2. Triggers

Flow 15 has three independent trigger paths. Each path is mutually exclusive at entry; all converge on Discord sync and registry update steps.

(Source: Zapier Integration V7.pdf §Flow 15 lines 2007–2038 · CR-20260818-001 — Flow 7 Pod Impact & Dispersal)

Release scope (Client confirmation 2026-10-30) — see BR_8.2.9.11:

---

3. Pre-conditions

---

4. Post-conditions

---

5. Basic Flow

Trigger A — Leader Status Change (Auto Cascade)

Step A-1. Detect Status Change

• Zapier catches the status change event on Pod_Leader_Registry where Pod_Status IN ('Suspended', 'Terminated').
• This event fires from three sources:
  • BPS Admin manual action — Admin sets Pod_Status directly via BPS.
  • POD_LEADER_TERMINATED webhook from Flow 7 — Flow 7 (UC_9.10 — Pod Impact & Dispersal) fires this webhook on Condition B (leader terminated mid-cycle). On receipt, Middleware automatically executes UPDATE Pod_Leader_Registry SET Pod_Status = 'Terminated' before kicking off the re-assignment cascade. (Source: CR-20260818-001)
  • Flow 4B Defense path — When Flow 4B (Drawdown Defense Re-Activation) activates and detects Users.is_pod_leader == True: (1) account enters 48h Defense freeze (account locked immediately); (2) after freeze, Middleware sets Pod_Leader_Registry.Status = 'Suspended'; (3) Users.stagnation_deadline = Today + 60 Days (Performance Improvement Plan timer — per CR-64); (4) pod dissolved and this Trigger A cascade executes. Trader is ineligible for pod activities for the 60-day PIP period. Re-activation path after passing PIP: Flow 15B (UC_8.2.10). (Source: CR-64)
• Query: Find all active mentees where Pod_Leader_ID = [Failed_Leader_ID].

Step A-2. Re-match Mentees

• Loop through mentee list → execute Flow 10 Matching Script (Python) against Pod_Leader_Registry for each mentee.
• Criteria Waterfall (per Flow 10): 1. Asset Match (Strict) → 2. Style Match → 3. Fallback: Lowest Current_Count.
• If match found: assign in DB, increment new leader's Current_Count.
• If no match (all leaders at Max_Capacity = 7): set mentee Pod_Status = 'Pod_Waitlist'.

Step A-3. Set Leader Status

• Pod_Status = 'Acting_Cover' if trigger reason = Suspended (temporary).
• Pod_Status = 'Reassigned' if trigger reason = Terminated (permanent).

(Source: Zapier Integration V7.pdf §Flow 15 Trigger A lines 2008–2023)

Step A-4. Discord Operations (Archive-First Pattern)

To avoid race conditions and orphan interactions in active pod channels, calls MUST follow the archive-first sequence.

• Step A-4.1 — Archive Channel (always first):

  • Call POST /archive-pod-channel with pod_leader_id: [Failed_Leader_ID].
  • Bot immediately revokes read/write access for all pod members (leader + all mentees), renames channel from pod-[leader_name] to archived-pod-[leader_name], clears channel_url in Pod_Leader_Registry.
  • Rationale: channel is frozen for everyone simultaneously before any role change occurs, eliminating the window where the channel is live but leaderless.

• Step A-4.2 — Revoke Leader Role:

  • Call POST /manage-discord-role with action: "REMOVE", role_name: "Pod Leader", user_id: [Failed_Leader_ID].

• Step A-4.3 — Full Digital Eviction (Termination only — Trigger A via Flow 7 or Flow 15C):

  • Call POST /discord/revoke-all-roles to strip all Title Roles (Associate / Trader / Senior), Pod Roles, and Special Roles from the terminated leader's account.
  • The user account remains on the server as a general/unverified member — NOT kicked or banned unless Admin takes further manual action.
  • This step is skipped for Suspension; only A-4.1 + A-4.2 apply.

• Step A-4.4 — Mentee Re-Sync (after Flow 10 reassignment in Step A-2):

  • For each mentee re-assigned to a new Pod Leader: revoke access to the old pod channel (already archived), grant access to new pod channel, sync Mentee roles for new pod.
  • Call POST /manage-discord-role per mentee for new pod channel access.

Step A-5. Notify

• Send Pod_Reassigned_Notification email to each re-assigned mentee ("Meet your new mentor").

Step A-6. Carry Balance Liquidation (Termination only)

• IF trigger reason = Terminated:
  • Liquidate Pending_Carry_Balance → Stack General Account (forfeit).
  • Set Pending_Carry_Balance = $0.00.

(Source: Zapier Integration V7.pdf §Flow 15 Trigger A line 2023)

---

Trigger B — BPS Admin Override

Step B-1. Receive Webhook

• Zapier catches webhook from Middleware POST /admin-pod-reassignment.
• Required payload: user_id, new_pod_id (nullable — null = remove from pod without reassigning), admin_id, reason, transcript_url, request_id (UUID — required for idempotency).
• Optional payload field: force_override (boolean, default false) — when true, bypasses the 30-day cooldown check.
• If any required field missing → Middleware returns 400 Bad Request before webhook fires. Zapier never receives malformed payload.

Step B-1.5. Idempotency Check (Dedup Gate)

• Middleware checks request_id against Redis Cache (key: pod-reassign:{request_id}, TTL: 24h).
• First call (key absent): Store key in Redis → proceed to Step B-2.
• Duplicate call (key exists — e.g. Zapier retry): Return cached 200 OK immediately. No DB writes, no Discord API calls, no email sends. Flow terminates here.
• Rationale: 30-day cooldown guards against repeated admin intent across days/months; idempotency key guards against Zapier network-timeout retries within the same operation window.

(Source: Client supplement 2026-10-06 — Q20(a) Trigger B dedup mechanism)

Step B-2. Cooldown Check

• Middleware queries pod_reassignment_date for user_id.
• IF force_override = true → bypass cooldown; proceed. Middleware must log the override to BPS_Audit_Log and fire an automated Slack alert to the #ops-it Operations channel, including admin_id, reason, transcript_url, and override flag.
• IF force_override = false (or absent) AND last transfer < 30 days ago → return 429 Too Many Requests (Cooldown Active). Flow terminates.
• IF NULL or ≥ 30 days → proceed.

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §Admin Pod Reassignment lines 2788–2800; Client confirmation 2026-09-20 — force_override break-glass)

Step B-3. Discord Sync

• Call Discord Bot API:
  • Remove roles for old_pod_id.
  • Assign roles for new_pod_id (skip if new_pod_id is null).

Step B-4. Registry Update

• Update pod_leader_id in Users table.
• Set pod_reassignment_date = Today.
• Update Current_Count for both old and new Pod Leaders in Pod_Leader_Registry to maintain accurate capacity tracking.

Step B-5. Notify

• Send Pod_Reassigned_Notification email to trader.
• Send Slack alert to old and new Pod Leaders.

(Source: Zapier Integration V7.pdf §Flow 15 Trigger B lines 2027–2034)

---

Trigger C — Leader Ineligibility

Step C-1. Receive Flag

• BPS Admin calls POST /api/bps/mentor/revoke to mark the leader as permanently ineligible.
• Middleware executes: UPDATE Pod_Leader_Registry SET Status = 'Permanently_Ineligible'.

Step C-2. Fire Offboarding Webhook

• Middleware fires POD_LEADER_TERMINATED webhook event to Zapier.
• This triggers the same Mentee Dispersal Cascade as Trigger A (Termination path).

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §BPS Endpoints — POST /api/bps/mentor/revoke)

Step C-3. Mentee Dispersal Cascade (inherits Flow 15A/15C behavior)

• Query all active mentees where pod_leader_id = [Ineligible_Leader_ID].
• Re-run Flow 10 Matching Engine for each mentee → assign to new active leader or FIFO Waitlist.
• Discord offboarding (archive-first pattern):
  • Call POST /archive-pod-channel — channel locked and renamed to archived-pod-[leader_name].
  • Call POST /manage-discord-role with action: "REMOVE", role_name: "Pod Leader".
• Carry balance: forfeit Pending_Carry_Balance = $0.00 to Stack General Account (same treatment as Termination).
• Send Pod_Reassigned_Notification email to each affected mentee.

Step C-4. Permanent Future Exclusion

• Flow 10 matching filters on Status = 'Active' AND Current_Count < Max_Capacity. Permanently_Ineligible record is excluded from all future match cycles automatically.

(Source: Zapier Integration V7.pdf §Flow 15 Trigger C lines 2035–2038 · RFQ_ Stack Trading Prop Tech V7.pdf §POST /api/bps/mentor/revoke)

---

6. Alternative Flows

Alt-1 — No available Pod Leader for re-matched mentee:

• Flow 10 matching returns no result (all leaders at Max_Capacity = 7).
• Mentee placed on FIFO Pod_Waitlist. Pod_Waitlist_Notification email sent.
• Plan_Due SLA freeze: When a mentee is placed on Pod_Waitlist, their Plan_Due timestamp (72-hour trading plan submission deadline) is paused. The 72-hour clock resets and starts only after the system successfully matches and assigns the mentee to a new Pod Leader. A mentee cannot submit a trading plan without an assigned mentor.
• Mentee re-enters matching queue when Current_Count decreases (Flow 11 trigger).

(Source: Client confirmation 2026-09-20 — "The 72-hour SLA deadline must be frozen")

Alt-2 — Pod Leader suspended (not terminated) — Pending_Carry_Balance handling:

• Pending_Carry_Balance is frozen (on hold) — NOT forfeited. Balance remains intact in the database.
• Vesting resumes when the leader's status returns to Active.
• Forfeiture to Stack General Account applies only on permanent Termination (Step A-6).

(Source: Client confirmation 2026-09-20 — "the pending carry balance is temporarily frozen on hold until their return")

---

Alt-3 — Defense-triggered Suspension: re-activation after PIP:

• After Flow 4B sets Pod_Leader_Registry.Status = 'Suspended', the trader enters a 60-day PIP period (stagnation_deadline = Today + 60 Days per CR-64).
• During PIP: Pending_Carry_Balance is frozen (BR_8.2.9.3), trader ineligible for all pod activities (cannot opt-in or be matched as Pod Leader).
• If trader passes PIP: re-activation follows Flow 15B (UC_8.2.10) — Pod Leader Opt-In & Provisioning. stagnation_deadline resets to Today + 90 Days on re-activation.
• If trader fails PIP (terminated): Pending_Carry_Balance forfeited per BR_8.2.9.3.

---

7. Exceptional Flows

Exc-1 — discord_user_id is NULL when calling POST /manage-discord-role:

• Middleware logs warning code DISCORD_USER_NOT_LINKED, bypasses the Discord API call, and returns 200 OK to Zapier.
• Zapier automation does NOT crash. DB and registry updates proceed normally.
• (Source: RFQ_ Stack Trading Prop Tech V7.pdf §Manage Discord Role lines 2335–2350)

Exc-2 — POST /archive-pod-channel fails:

• Internal Retry: Middleware retries max 3× with Exponential Backoff on HTTP 429, HTTP 404, or Timeout.
• After 3 failures:
  • Log entry written to bps_audit_logs with severity = WARN.
  • channel_url set to NULL in Pod_Leader_Registry — pod state cleared regardless of Discord outcome.
  • Slack alert to #dev_ops: "⚠️ WARNING: Failed to archive Discord channel for Pod Leader [Leader_ID]. Manual cleanup required."
  • Middleware returns HTTP 200 OK: { "status": "success", "channel_archived": false, "warning": "Discord API timeout, logged for manual cleanup" }.
• Zapier behavior: Receives 200 OK → continues non-blocking to next step (mentee re-matching).

(Source: Client confirmation 2026-09-18)

Exc-3 — Trigger B payload missing required field:

• Middleware validates before firing webhook. Returns 400 Bad Request.
• Zapier flow never triggered. Audit log entry written by Middleware.

---

8. Discord Access & Role Management Specification

This section consolidates the full Discord integration specification for Flow 15A (re-assignment) and Flow 15C (offboarding). It is the authoritative reference for all Discord API calls triggered by Pod Leader status changes.

A. Offboarding Actions for Terminated / Suspended Leader

Detailed steps:

1. Revoke Leader Role: Call POST /manage-discord-role with action: "REMOVE", role_name: "Pod Leader".
2. Archive Pod Channel: Call POST /archive-pod-channel:
   • Removes read/write permissions for all former pod members.
   • Renames channel from pod-[leader_name] to archived-pod-[leader_name].
   • Clears channel_url in Pod_Leader_Registry.
3. Full Digital Eviction — Termination only: Call POST /discord/revoke-all-roles to strip all Title Roles (Associate / Trader / Senior), Pod Roles, and Special Roles. The user account remains on the server as a general/unverified member with restricted access. Manual kick/ban by Admin is required for misconduct cases — not automated.

B. Failsafe — Null discord_user_id

If discord_user_id IS NULL in the Users table when any Discord API call is attempted, Middleware MUST:

• Log warning code DISCORD_USER_NOT_LINKED.
• Bypass the API call entirely.
• Return HTTP 200 OK to preserve workflow execution integrity.

The flow must not crash or halt due to a missing Discord link.

C. Re-Sync for Dispersed Mentees

Upon successful reassignment to a new Pod Leader (via Flow 10):

• Revoke the Mentee's access to the old_pod_id Discord channel.
• Grant access to the new_pod_id Discord channel.
• Sync relevant Mentee roles for the new pod.

(Source: Client supplement 2026-10-05 — §3.8 Discord Access & Role Management Specification)

---

9. Business Rules

BR_8.2.9.1: Matching Waterfall — Asset Match is Strict

When re-assigning mentees via Flow 10 matching logic, Asset Class match (Futures vs. Forex) is a hard filter — not a preference. A Futures trader cannot be assigned to a Forex Pod Leader regardless of capacity.

(Source: Zapier Integration V7.pdf §Flow 10 Step 3 line 1824)

BR_8.2.9.2: Cooldown — 30-Day Transfer Limit per Trader (Trigger B) + Force Override Break-Glass

Admin-manual re-assignments via POST /admin-pod-reassignment are subject to a 30-day cooldown per user_id. If the last pod_reassignment_date is within 30 days, Middleware returns 429 Too Many Requests.

Break-glass override: Admin may pass force_override = true in the payload to bypass the 30-day cooldown. When this flag is set, Middleware must: (1) bypass the cooldown check; (2) write a mandatory BPS_Audit_Log entry flagging the override; (3) fire an automated Slack alert to the Operations channel with admin_id, reason, transcript_url, and override flag.

This cooldown does not apply to Trigger A (system-automated) or Trigger C (eligibility flag).

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §Admin Pod Reassignment lines 2795–2800; Client confirmation 2026-09-20)

BR_8.2.9.3: Carry Balance — Frozen on Suspension, Forfeited on Termination

• Suspension: Pending_Carry_Balance is frozen (on hold) — NOT forfeited. Vesting resumes when Pod_Leader_Status returns to Active.
• Termination: Pending_Carry_Balance is immediately liquidated to the Stack General Account and reset to $0.00. No grace period or partial vesting.

(Source: Zapier Integration V7.pdf §Flow 15 Trigger A line 2023; Client confirmation 2026-09-20)

BR_8.2.9.4: Permanently_Ineligible Exclusion from Matching

A Pod_Leader_Registry record with Status = 'Permanently_Ineligible' must be excluded from all Flow 10 matching queries. This is a permanent, non-reversible flag from the matching algorithm's perspective.

(Source: Zapier Integration V7.pdf §Flow 15 Trigger C lines 2036–2038)

BR_8.2.9.5: BPS Audit Log Mandatory for Admin Actions

All Trigger B actions must log admin_id, reason, and transcript_url to the BPS_Audit_Log table. Actions without a complete audit trail are not compliant.

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §BPS Audit Log lines 2724–2761)

BR_8.2.9.6: Discord Resiliency — NULL user_id Must Not Crash Flow

POST /manage-discord-role must return 200 OK when discord_user_id IS NULL in the PostgreSQL database. The Node.js middleware drops the Discord action silently. This prevents Zapier automation from crashing when a trader has not yet linked their Discord account.

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §Manage Discord Role lines 2345–2350)

BR_8.2.9.8: Full Digital Eviction — Termination Only

When a Pod Leader is permanently terminated (via Flow 7 / Flow 15C), Middleware MUST call POST /discord/revoke-all-roles to strip all Discord roles (Title Roles: Associate / Trader / Senior; Pod Roles; Special Roles) in addition to the standard POST /manage-discord-role REMOVE "Pod Leader" and POST /archive-pod-channel calls.

This triple-call sequence is exclusive to Termination. Suspension triggers only the first two calls (role removal + channel archive) — POST /discord/revoke-all-roles is skipped for suspended leaders.

The terminated user's Discord account is NOT automatically kicked or banned from the server. The user retains general/unverified member status. Kick or ban requires manual Admin action.

(Source: Client supplement 2026-10-05 — §3.8A Full Digital Eviction)

BR_8.2.9.9: Mentee Discord Re-Sync on Reassignment

When a Mentee is successfully reassigned to a new Pod Leader via Flow 10, the Discord sync MUST: (1) revoke the Mentee's access to the old pod's Discord channel (old_pod_id); (2) grant access to the new pod's Discord channel (new_pod_id); (3) sync relevant Mentee roles for the new pod. This re-sync is part of the Flow 15 → Flow 10 handoff sequence, not a separate manual step.

(Source: Client supplement 2026-10-05 — §3.8C Re-Sync for Dispersed Mentees)

---

BR_8.2.9.10: Defense-Triggered Pod Leader Suspension Path

When Flow 4B (Drawdown Defense Re-Activation) fires and Users.is_pod_leader == True, the following sequence is mandatory:

1. Immediate 48h Defense Freeze: Account locked. No trading or pod management activity permitted.
2. Suspended Status Written: After the 48h freeze, Middleware sets Pod_Leader_Registry.Status = 'Suspended'.
3. PIP Timer: Users.stagnation_deadline = Today + 60 Days (unconditional — per CR-64). Trader is ineligible for pod activities for the full 60-day PIP period.
4. Pod Dissolution: Flow 15A Trigger A cascade executes — pod dissolved, mentees re-assigned via Flow 10, Discord offboarded (archive-first pattern).
5. Carry Balance: Pending_Carry_Balance frozen (NOT forfeited) per BR_8.2.9.3 — Suspension, not Termination.
6. Re-activation: If trader passes PIP → Flow 15B (UC_8.2.10) re-provisions Pod Leader identity. If trader fails PIP (Terminated) → Pending_Carry_Balance forfeited.

(Source: CR-64; user spec 2026-10-09 §3 — Drawdown Defense ↔ Pod Mentorship Engine closed-loop spec)

---

BR_8.2.9.11: Phased Rollout — Trigger A in Phase 1; Triggers B & C in Phase 2 (Release 2)

• Phase 1 (Go-Live): Only Trigger A is implemented — automated Pod dissolution, Flow 10 mentee re-matching, and Discord role/channel archiving.
• Phase 2 (Release 2): Trigger B (manual mentee reassignment via BPS Admin) and Trigger C (manual Permanent Ineligibility toggle via BPS Admin) are deferred to Phase 2 alongside the BPS Admin Portal rollout. Trigger A source (1) "BPS Admin manual status change" also moves from backend script to the BPS Admin Portal UI in Phase 2. ACs for Trigger B/C (AC-8.2.9-04, -05, -06, -07, -09) are Phase 2 test scope.
• Phase 1 manual overrides: Rare manual overrides are handled by backend scripts, not by a BPS Admin UI.
• Carry guardrail on Trigger A: Pending_Carry_Balance is forfeited (set to $0.00) only when a Pod Leader is permanently Terminated (Flow 7 Termination / Flow 15C). When a Pod Leader is temporarily Suspended by Drawdown Defense (Flow 4B), the Pod is dissolved and mentees are reassigned, but Pending_Carry_Balance is frozen — held in the database until the leader passes PIP and returns to Active — not forfeited (BR_8.2.9.3).

(Source: Client confirmation 2026-10-30 — incl. Stage 6 Pod Leader sheet Row 10 carry guardrail)

---

When a mentee is placed on Pod_Waitlist (no available Pod Leader at re-assignment time), their Plan_Due timestamp (72-hour trading plan submission SLA) must be paused in the database. The 72-hour clock does not run while the mentee has no assigned mentor. The clock resets and resumes only after the system successfully matches and assigns the mentee to a new Pod Leader.

(Source: Client confirmation 2026-09-20 — "The 72-hour SLA deadline must be frozen. A mentee cannot submit a trading plan to a mentor they lack.")

---

10. Data Model

Pod_Leader_Registry (native PostgreSQL table) — relevant fields

(Source: Zapier Integration V7.pdf §Table E lines 777–790 — naming reference only; Pod_Leader_Registry is native PostgreSQL, see Document References note)

State Machine — Pod Leader Status Through Defense Cycle

(Source: user spec 2026-10-09 §5 — Defense ↔ Pod state machine)

Users Table (relevant fields)

---

11. API Reference

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §BPS Endpoints; §Manage Discord Role; §Archive Pod Channel; §POST /api/bps/mentor/revoke)

---

12. Email Templates

---

13. Acceptance Criteria

---

14. Changelog