docs(sp39): RUNBOOK + submission/core.py TODO for upstream trace follow-up

backend/src/cyclone/submission/core.py

@@ -37,6 +37,11 @@ log = logging.getLogger(__name__)
 
 # The companion-guide payer id we enforce for CO Medicaid submits.
 # Same value the legacy ``resubmit-rejected-claims`` CLI gates on.
+# TODO(sp39-followup): trace where ClaimOutput.payer.id gets set to
+# "SKCO0" upstream of submit. SP39 hard-fixes the serializer via
+# _normalize_payer_id (serialize_837.py) so the byte defect cannot
+# escape the 837 emit, but the root-cause setter is still live in the
+# raw_json pipeline. Find and patch in a future SP.
 EXPECTED_PAYER_ID = "CO_TXIX"
 
 

docs/RUNBOOK.md

@@ -247,6 +247,37 @@ from cyclone.parsers.parse_999 import parse as parse_999
 result = parse_999(open("path.999.x12").read())
 ```
 
+### After SP39 lands — corrected-claim push + tracking
+
+The corrected files now live under
+`ingest/corrected-v2/v2-batch-<batch-id>-<N>-claims/` instead of the
+SP33-era `ingest/corrected/batch-<id>-<N>-claims/` tree. The
+originals are preserved for postmortem; the new tree is the
+resubmission payload. Push workflow:
+
+1. `cyclone resubmit-rejected-claims --ingest-dir /home/tyler/dev/cyclone/ingest/corrected-v2`
+   (one push per batch dir; the CLI is idempotent on
+   `(claim_id, interchange_control_number)` so re-running is safe).
+2. After Gainwell returns 999 acks, drop them into `ingest/` for
+   the standard `cyclone pull-inbound` flow.
+3. Track the post-submission outcomes:
+   `cyclone resubmissions status [--batch-id=<id>]` — shows
+   `pending_999 / 999_accepted / 999_rejected / 277ca_accepted /
+   paid / denied_again` per claim, joined against `claim_acks`
+   (via the existing SP28/31 auto-link) and `remittances` (via
+   CLP→claim).
+
+What SP39 fixed in the serializer (2010BB loop, payer NM1 segment):
+
+- Empty / `SKCO0` / `CO_BHA` payer.id → normalized to `CO_TXIX`
+  (Gainwell's companion guide requires `CO_TXIX` for the 2010BB
+  NM109; `SKCO0` and `CO_BHA` were silently accepted by Gainwell's
+  pre-processor in late 2025 but their SET-level structural
+  validator rejects them as of 2026-07).
+- Empty / `COHCPF` / `CO_BHA` payer.name → normalized to `CO_TXIX`.
+- Foreign payer IDs (anything else) pass through verbatim with a
+  WARNING log per substitution.
+
 ### Switching from manual → real (and back)
 
 When this host's IP is whitelisted with Gainwell's MFT admin, the