docs: add implementation plan for #398 #400 #401

docs/plans/2026-03-03-398-400-401-implementation.md

@@ -0,0 +1,281 @@
+# 398/400/401 Integration Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Implement #398, #400, #401 as three isolated PRs targeting `feature/398-400-401`, merge only when CI passes and self-review has zero minor issues, then run and monitor overnight script without stopping the process.
+
+**Architecture:** Create one integration base branch from `origin/main`, branch per issue, and ship in strict sequence (`398 -> 400 -> 401`) to keep diffs isolated. Use TDD per issue (fail-first tests, minimal fix, regression checks), then perform PR self-review and CI gate before merge. After all merges, run overnight in background and monitor logs/process health while leaving runtime active.
+
+**Tech Stack:** Python 3, pytest, asyncio runtime loop, Git/Gitea (`tea`), shell scripts (`scripts/run_overnight.sh`).
+
+---
+
+### Task 1: Prepare Integration Branch Topology
+
+**Files:**
+- Modify: `.git` refs only (branch operations)
+
+**Step 1: Sync base branch**
+
+Run: `git fetch origin && git checkout main && git pull --ff-only origin main`
+Expected: local `main` equals `origin/main`
+
+**Step 2: Create integration branch**
+
+Run: `git checkout -b feature/398-400-401`
+Expected: current branch is `feature/398-400-401`
+
+**Step 3: Create issue branches from integration branch**
+
+Run: `git checkout -b fix/398 && git checkout feature/398-400-401 && git checkout -b fix/400 && git checkout feature/398-400-401 && git checkout -b fix/401 && git checkout feature/398-400-401`
+Expected: three issue branches exist and point to same base commit
+
+**Step 4: Push all branches**
+
+Run: `git push -u origin feature/398-400-401 fix/398 fix/400 fix/401`
+Expected: remote tracking set for all four branches
+
+**Step 5: Commit checkpoint**
+
+Run:
+```bash
+git status --short
+```
+Expected: clean workspace before issue implementation
+
+### Task 2: Implement #398 with TDD (KR rt_cd failure handling)
+
+**Files:**
+- Modify: `src/main.py`
+- Test: `tests/test_main.py`
+
+**Step 1: Write failing test**
+
+Add test in `tests/test_main.py` verifying KR order returns `rt_cd != '0'` does not trigger success side effects (no BUY notify, no trade log success path).
+
+**Step 2: Run test to verify failure**
+
+Run: `pytest tests/test_main.py -k "kr and rt_cd" -v`
+Expected: FAIL showing current code incorrectly treats KR order as success
+
+**Step 3: Write minimal implementation**
+
+In KR order branch of `src/main.py`, immediately after `send_order`, add `rt_cd` acceptance check identical to overseas branch behavior; set `order_succeeded = False` and warning log when rejected.
+
+**Step 4: Run targeted tests**
+
+Run: `pytest tests/test_main.py -k "kr and rt_cd" -v`
+Expected: PASS
+
+**Step 5: Run safety regression**
+
+Run: `pytest tests/test_main.py tests/test_order_policy.py -q`
+Expected: PASS
+
+**Step 6: Commit**
+
+Run:
+```bash
+git add tests/test_main.py src/main.py
+git commit -m "fix: handle KR order rejection via rt_cd check (#398)"
+```
+
+### Task 3: Open PR for #398, Self-review, CI gate, Merge
+
+**Files:**
+- Modify: remote PR metadata/comments only
+
+**Step 1: Push branch**
+
+Run: `git checkout fix/398 && git push -u origin fix/398`
+
+**Step 2: Create PR targeting integration branch**
+
+Run: `tea pr create --base feature/398-400-401 --head fix/398 --title "fix: #398 KR rt_cd rejection handling" --description "Implements issue #398 with tests."`
+Expected: PR URL returned
+
+**Step 3: Add self-review comment (severity rubric)**
+
+Run: `tea pr comment <PR_398> --message "Self-review: Critical 0 / Major 0 / Minor 0. Merge allowed when CI passes."`
+
+**Step 4: Wait for CI success**
+
+Run: `tea pr checks <PR_398>` (poll until all success)
+Expected: all checks success
+
+**Step 5: Merge only when gate passes**
+
+Run: `tea pr merge <PR_398> --delete-branch=false`
+Expected: merged into `feature/398-400-401`
+
+### Task 4: Implement #400 with TDD (US session transition correctness)
+
+**Files:**
+- Modify: `src/main.py`, `src/core/order_policy.py`, `src/markets/schedule.py`
+- Test: `tests/test_main.py`, `tests/test_market_schedule.py`, `tests/test_order_policy.py`
+
+**Step 1: Write failing tests**
+
+Add tests for:
+- session transition event handling (`US_DAY -> US_REG`) emits open event and forces rescan
+- `US_DAY` treated non-tradable for playbook/trading actions
+
+**Step 2: Run failing tests**
+
+Run: `pytest tests/test_main.py tests/test_market_schedule.py tests/test_order_policy.py -k "US_DAY or US_REG or session" -v`
+Expected: FAIL at current behavior
+
+**Step 3: Minimal implementation**
+
+- Track market state by session identifier (not bool only)
+- Force rescan/playbook refresh on US_REG entry
+- Exclude/suppress US_DAY for trading/playbook generation path
+
+**Step 4: Re-run targeted tests**
+
+Run: same command as Step 2
+Expected: PASS
+
+**Step 5: Regression pass**
+
+Run: `pytest tests/test_main.py tests/test_market_schedule.py tests/test_order_policy.py tests/test_pre_market_planner.py -q`
+Expected: PASS
+
+**Step 6: Commit**
+
+Run:
+```bash
+git add src/main.py src/core/order_policy.py src/markets/schedule.py tests/test_main.py tests/test_market_schedule.py tests/test_order_policy.py
+git commit -m "fix: handle US session transitions and suppress US_DAY trading (#400)"
+```
+
+### Task 5: Open PR for #400, Self-review, CI gate, Merge
+
+**Files:**
+- Modify: remote PR metadata/comments only
+
+**Step 1: Push branch**
+
+Run: `git checkout fix/400 && git push -u origin fix/400`
+
+**Step 2: Create PR**
+
+Run: `tea pr create --base feature/398-400-401 --head fix/400 --title "fix: #400 US session transition handling" --description "Implements issue #400 with tests."`
+
+**Step 3: Add self-review comment**
+
+Run: `tea pr comment <PR_400> --message "Self-review: Critical 0 / Major 0 / Minor 0. Merge allowed when CI passes."`
+
+**Step 4: Wait for CI success**
+
+Run: `tea pr checks <PR_400>`
+Expected: all checks success
+
+**Step 5: Merge**
+
+Run: `tea pr merge <PR_400> --delete-branch=false`
+
+### Task 6: Implement #401 with TDD (multi-market parallel processing)
+
+**Files:**
+- Modify: `src/main.py`
+- Test: `tests/test_main.py`
+
+**Step 1: Write failing tests**
+
+Add tests verifying:
+- open markets are processed via parallel task dispatch
+- circuit breaker behavior still triggers global shutdown semantics
+- shared state updates remain deterministic under parallel market execution
+
+**Step 2: Run failing tests**
+
+Run: `pytest tests/test_main.py -k "parallel or market" -v`
+Expected: FAIL before implementation
+
+**Step 3: Minimal implementation**
+
+Refactor sequential market loop into market-level async tasks (`asyncio.gather`/task group) while preserving stock-level processing order per market and existing failure semantics.
+
+**Step 4: Re-run targeted tests**
+
+Run: same command as Step 2
+Expected: PASS
+
+**Step 5: Regression pass**
+
+Run: `pytest tests/test_main.py tests/test_runtime_overnight_scripts.py -q`
+Expected: PASS
+
+**Step 6: Commit**
+
+Run:
+```bash
+git add src/main.py tests/test_main.py
+git commit -m "feat: process active markets in parallel with preserved shutdown semantics (#401)"
+```
+
+### Task 7: Open PR for #401, Self-review, CI gate, Merge
+
+**Files:**
+- Modify: remote PR metadata/comments only
+
+**Step 1: Push branch**
+
+Run: `git checkout fix/401 && git push -u origin fix/401`
+
+**Step 2: Create PR**
+
+Run: `tea pr create --base feature/398-400-401 --head fix/401 --title "feat: #401 parallel multi-market processing" --description "Implements issue #401 with tests."`
+
+**Step 3: Add self-review comment**
+
+Run: `tea pr comment <PR_401> --message "Self-review: Critical 0 / Major 0 / Minor 0. Merge allowed when CI passes."`
+
+**Step 4: Wait for CI success**
+
+Run: `tea pr checks <PR_401>`
+Expected: all checks success
+
+**Step 5: Merge**
+
+Run: `tea pr merge <PR_401> --delete-branch=false`
+
+### Task 8: Final Branch Validation + Overnight Runtime Monitoring
+
+**Files:**
+- Execute: `scripts/run_overnight.sh`
+- Observe: runtime log file (e.g., `logs/overnight.log`)
+
+**Step 1: Checkout integrated branch and sync**
+
+Run: `git checkout feature/398-400-401 && git pull --ff-only origin feature/398-400-401`
+Expected: branch contains merged PRs
+
+**Step 2: Start overnight in background (non-blocking)**
+
+Run:
+```bash
+nohup ./scripts/run_overnight.sh > /tmp/ouroboros_overnight.log 2>&1 &
+echo $! > /tmp/ouroboros_overnight.pid
+```
+Expected: PID written and process running
+
+**Step 3: Verify process alive**
+
+Run: `ps -p $(cat /tmp/ouroboros_overnight.pid) -o pid,ppid,stat,etime,cmd`
+Expected: process present
+
+**Step 4: Monitor startup logs**
+
+Run: `tail -n 120 /tmp/ouroboros_overnight.log`
+Expected: startup complete and runtime loop active without fatal errors
+
+**Step 5: Ongoing monitor without shutdown**
+
+Run: `tail -f /tmp/ouroboros_overnight.log` (sample monitoring window, then detach)
+Expected: continued activity; do not kill process
+
+**Step 6: Final status note**
+
+Record PID, log path, and “process left running” status.