PR #482 Split — Design¶

Status: Frozen (2026-05-20). This document captures the state of the split as designed; the executed split lives in PRs #498–#502 and the matching commit history. Do not edit retroactively — for the actual outcome see git log and the linked PRs.

Date: 2026-05-20 Author: Alexander Medchenko (with Claude) Status: Frozen — superseded by the merged split PRs Source PR: tradai-bot/tradai#482 (fix/474-review-blockers-clean → main) Resulting PRs: #498 (security audit), #499 (demo scripts), #500 (backend traceability), #501 (verification scripts), #502 (Postman drift gate)

Problem¶

PR #482 has grown to 34 files, +2234 / −494, 11 commits. It bundles five unrelated concerns ("review blockers" from the merged-then-reverted #474). Reviewers cannot land it incrementally; mistakes in one area block the others. We want to split it into smaller logical PRs without losing work.

Goal¶

Split PR #482 into five focused, independently reviewable PRs that branch off main in parallel — none structurally depends on another. The original branch (fix/474-review-blockers-clean) is preserved untouched as a safety net until all five split PRs land.

Non-goals¶

Stacking PRs in a linear chain (graphite/spr style). The five concerns are independent; stacking would add rebase churn without benefit.
Rewriting #482's history. The branch stays as-is.
Combining splits. Each of the five concerns lands as its own PR.

Architecture¶

                    main (current HEAD)
                      │
       ┌─────┬────────┼────────┬─────┐
       ▼     ▼        ▼        ▼     ▼
   split/    split/   split/   split/  split/
  backend-  verif-   postman- demo-   security-
  traceab.  scripts  drift-   script- audit-
                     gate     fixes   refresh

   fix/474-review-blockers-clean  ← PR #482 (open as safety net)
   backup/pr-482-pre-split        ← tag added before any split work

Five branches, each based on origin/main, each its own PR. Reviewers can merge them in any order.

Extraction mechanics¶

Path-based extraction, not commit cherry-pick. The 11 commits in #482 do not align with the five logical groups (the first commit alone touches backend + verification + demo + Postman). Cherry-picking would conflict constantly.

Per split:

git checkout -b split/<name> origin/main
git checkout fix/474-review-blockers-clean -- <paths-for-this-group>
# Handle deletions separately when needed:
#   git rm <path-deleted-in-482>
git status                  # verify only expected paths staged
git diff --staged           # eyeball the diff
git commit -m "<focused message>"
git push -u origin split/<name>
gh pr create --base main \
  --title "..." \
  --body "Split from #482: <concern>. See #482 for combined context."

Why this is safe¶

Each split branch starts from clean origin/main. No inherited history from #482.
git checkout <src-branch> -- <path> only stages those exact paths.
The source branch (fix/474-review-blockers-clean) is never modified.
A backup/pr-482-pre-split tag is pushed before any split work, giving an unconditional fallback.

The five PRs¶

PR-1 `split/backend-traceability` (7 files, ~120 LOC)¶

Populate top-level mlflow_run_id on local / in-memory backtest paths so the trace context is complete, plus route and repository tests.

services/backend/src/tradai/backend/api/routes.py            (+4)
services/backend/src/tradai/backend/api/schemas.py           (+8)
services/backend/src/tradai/backend/core/settings.py         (+7 -2)
services/backend/src/tradai/backend/infrastructure/local.py  (+11 -1)
services/backend/src/tradai/backend/infrastructure/memory.py (+7 -1)
services/backend/tests/unit/test_backtest_routes.py          (+23)
services/backend/tests/unit/test_memory.py                   (+67 -1)

Title: fix(backend): populate top-level mlflow_run_id for local/in-memory backtest paths

PR-2 `split/verification-scripts` (~16 files; largest)¶

Relocate verification scripts from docs/verification/ to scripts/verification/, add issue-417 coverage scripts, and align endpoint docs with the new from_version/to_stage schema.

docs/reference/api.md                                       (+15 -12)
docs/verification/E2E-VERIFICATION-LOG.md                   (+1 -1)
docs/verification/e2e-verification-report-20260428.md       (+7 -7)
docs/verification/issue91-independent-verification-20260423.md (+2 -2)
docs/verification/issue91.md                                (+1 -1)
docs/verification/api-endpoint-audit.sh                     (DELETE: 289 lines; replaced by NEW under scripts/verification/)
docs/verification/config-versioning-e2e-aws.sh              (DELETE; renamed to scripts/verification/config-versioning-e2e-aws.sh)
docs/verification/issue89-verify.sh                         (DELETE; renamed to scripts/verification/issue89-verify.sh)
docs/verification/issue90-verify.sh                         (DELETE; renamed to scripts/verification/issue90-verify.sh)
docs/verification/issue91-verify.sh                         (DELETE; renamed to scripts/verification/issue91-verify.sh)
docs/verification/issue92-verify.sh                         (DELETE; renamed to scripts/verification/issue92-verify.sh)
scripts/verification/api-endpoint-audit.sh                  (NEW: 361)
scripts/verification/config-versioning-e2e-aws.sh           (renamed from docs/verification/)
scripts/verification/issue89-verify.sh                      (renamed; +10 J.3 SNS check)
scripts/verification/issue90-verify.sh                      (renamed from docs/verification/)
scripts/verification/issue91-verify.sh                      (renamed from docs/verification/)
scripts/verification/issue92-verify.sh                      (renamed from docs/verification/)
scripts/verification/issue-417-alarm-fire-coverage.sh       (NEW: 108)
scripts/verification/issue-417-auth-coverage.sh             (NEW: 120)
scripts/verification/issue-417-non-freqai-backtest.sh       (NEW: 102)
scripts/verification/issue-417-running-after-launch.sh      (NEW: 128)

Title: chore(verification): relocate audit scripts and add issue-417 coverage scripts

PR-3 `split/postman-drift-gate` (4 files; heaviest diff, single purpose)¶

Regenerate the Postman collection, add a drift gate to CI, ship the regenerator script and its unit test.

.github/workflows/ci.yml                                    (+5)
postman/aws-dev-tradai.postman_collection.json              (+833 -157)
scripts/dev/regenerate-postman-schemas.py                   (NEW: 250)
tests/unit/test_regenerate_postman_schemas.py               (NEW: 98)

Title: feat(postman): add schema drift gate and harden collection tests

PR-4 `split/demo-script-fixes` (5 files)¶

Restore alarm state after fire coverage, use sentinel cleanup names, align demo flows with the from_version/to_stage schema.

scripts/demo/06-results-kpis.sh         (+6 -4)
scripts/demo/11-promote-production.sh   (+5)
scripts/demo/13-rollback.sh             (+5)
scripts/demo/14-cleanup.sh              (+28)
scripts/demo/lib.sh                     (+1 -1)

Title: fix(demo): restore alarm state, use sentinel cleanup names, align with from_version schema

PR-5 `split/security-audit-refresh` (2 files)¶

Refresh pip-audit ignores and the matching lock file. Standalone because they're independent of every other change.

.pip-audit-ignore.txt   (NEW: +6)
uv.lock                 (+15 -15)

Title: chore(security): refresh pip-audit ignores and lock file

Judgment call¶

docs/reference/api.md is placed in PR-2 because it documents the validation behavior the new verification scripts assert (the 422 validation contract mentioned in the PR #482 description). It could equally live in PR-3 alongside the Postman collection. If reviewers prefer that grouping, move it during execution.

Recommended landing order¶

Order does not affect correctness — every split is independent. For review efficiency:

PR-5 security — tiny, fast review, gets it out of the way.
PR-4 demo — small, self-contained shell fixes.
PR-1 backend — focused code change with tests.
PR-2 verification — mostly relocation plus new scripts, low logic risk.
PR-3 Postman — heaviest diff because of generated JSON; save for last.

Risks and mitigations¶

Risk	Mitigation
Lose work during split	`backup/pr-482-pre-split` tag pushed before any split work; PR #482 stays open until all five splits merge.
Path mismatch on extraction	`git status` + `git diff --staged` reviewed before every commit. Verify expected file set.
Renamed files appear as add+delete	Acceptable. Unified PR view still shows the rename.
CI drift gate (PR-3) flags later PRs	Drift gate triggers when endpoint schemas change. PR-1 (backend traceability) touches `services/backend/src/tradai/backend/api/schemas.py` but only adds two optional `str \\| None` fields with backward-compatible defaults; the regenerated Postman snapshot in PR-3 already includes those fields, so the gate stays green when both PRs land. Verify the snapshot includes the new fields before merging PR-3, or rebase PR-3 onto a main that has PR-1.
Post-merge regression in a single split	Each split is independently revertable via `gh pr revert <split-pr-number>`. The `backup/pr-482-pre-split` tag and the original #482 branch remain available for re-extraction.
Forgotten file slips between splits	Final check: `git diff origin/main fix/474-review-blockers-clean -- <all-paths>` should equal the union of the five split diffs.
Spec accidentally lands on #482 branch	Spec is committed on its own `docs/pr-482-split-design` branch off `main`. No new commits are ever added to `fix/474-review-blockers-clean` during this work (it is read from, never written to).

What we'll do next (implementation plan input)¶

The writing-plans skill takes over from here. The plan must:

Create and push backup/pr-482-pre-split tag.
For each of the five splits, in order: create branch off origin/main, extract paths, verify diff, commit, push, open PR.
Run the union-diff sanity check after all five branches exist.
Leave PR #482 open with a comment listing the five split PRs.
Close PR #482 only after all five split PRs merge — that is a later step the user triggers manually.