docs(plan): SP33 Co TXIX payer fix implementation

docs/superpowers/plans/2026-07-02-cyclone-co-txix-payer-fix.md

@@ -0,0 +1,768 @@
+# SP33 — Co TXIX Payer Fix Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:executing-plans` (Tyler picked inline execution for SP33, single-operator night-shift). Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make dzinesco's CO Medicaid 837P submissions emit `NM1*PR*...*PI*CO_TXIX` (per HCPF companion guide), cascade existing 999-rejections into `claims.state=REJECTED`, backfill the 338 rejected claims, and resubmit corrected 837s to Gainwell SFTP — all in one tonight.
+
+**Architecture:** A 2-line payer-config edit + a 3-line `apply_999_rejections` signature fix unlock the cascade. Two new `cyclone.cli` subcommands do the backfill and the resubmit. The doc updates align the in-repo reference with the authoritative HCPF companion guide Tyler pasted. Atomic single merge into `main`.
+
+**Tech Stack:** Python 3.11, SQLAlchemy + SQLite/SQLCipher, paramiko (SFTP), pytest. Frontend untouched.
+
+**Spec:** [`docs/superpowers/specs/2026-07-02-cyclone-co-txix-payer-fix-design.md`](../specs/2026-07-02-cyclone-co-txix-payer-fix-design.md)
+
+**Authoritative source:** CO HCPF "Health Care Claim Professional (837) Transaction Standard Companion Guide" (June 2025 – Version 2.5). Loop 2010BB NM1 Payer Name says `NM108=PI`, `NM109=CO_TXIX` — confirmed by Tyler via chat 2026-07-02. In-repo reference for shape: [`docs/goodclaim.x12`](../../goodclaim.x12).
+
+---
+
+## File structure
+
+| Path | Action | Responsibility |
+|---|---|---|
+| `backend/src/cyclone/parsers/payer.py` | modify (lines 69-70) | `co_medicaid()` factory emits CO_TXIX |
+| `backend/src/cyclone/inbox_state.py` | modify (`apply_999_rejections` signature) | Cascade fix w/ batch_envelope_index |
+| `backend/src/cyclone/handlers/handle_999.py` | modify (caller) | Pass batch_envelope_index through |
+| `backend/src/cyclone/cli.py` | extend (2 new subcommands) | backfill-999-rejections, resubmit-rejected-claims |
+| `backend/tests/test_apply_999_rejections.py` | create | Cascade-fix coverage |
+| `backend/tests/test_serialize_837.py` | extend | Round-trip with CO_TXIX |
+| `docs/reference/837p.md` | modify (line 48) | Doc update |
+| `docs/reference/co-medicaid.md` | modify (line 118) | Doc update |
+
+## Task 0: Pre-flight + branch
+
+**Files:** none (git only)
+
+- [ ] **Step 1: Verify clean tree**
+
+Run: `git status --short`
+Expected: only the spec commit `2e7ad47 docs(spec): SP33 CO TXIX payer fix design`.
+
+- [ ] **Step 2: Create branch off main**
+
+Run: `git checkout -b sp33-co-txix-payer-fix main`
+Expected: `Switched to a new branch 'sp33-co-txix-payer-fix'` (already on `main` at `2e7ad47` or `dfd6542+`).
+
+- [ ] **Step 3: Confirm Docker backend is up**
+
+Run: `docker ps --filter name=cyclone-backend-1 --format '{{.Names}} {{.Status}}'`
+Expected: `cyclone-backend-1 Up X minutes (healthy)`.
+
+## Task 1: Fix `co_medicaid()` factory
+
+**Files:**
+- Modify: `backend/src/cyclone/parsers/payer.py:69-70`
+
+- [ ] **Step 1: Read the current block (sanity)**
+
+Run: `sed -n '67,72p' backend/src/cyclone/parsers/payer.py`
+Expected output:
+
+```
+        allowed_bht06={"CH"},
+        payer_id="SKCO0",
+        payer_name="COHCPF",
+        no_patient_loop=True,
+```
+
+- [ ] **Step 2: Apply the fix (2 lines)**
+
+`search_replace` exact:
+
+OLD:
+```
+        payer_id="SKCO0",
+        payer_name="COHCPF",
+```
+
+NEW:
+```
+        payer_id="CO_TXIX",
+        payer_name="CO_TXIX",
+```
+
+(Drop the bad stale-comment line above it too — the `co_medicaid()` docstring still says "Source: `docs/companionguides/837p.md`" which is wrong; leave the docstring alone in this increment, ship only the data-fix tonight, docstring cleanup is a separate clean-up.)
+
+- [ ] **Step 3: Verify the diff**
+
+Run: `git diff backend/src/cyclone/parsers/payer.py`
+Expected: a 2-line change, exactly the two `payer_id`/`payer_name` lines.
+
+- [ ] **Step 4: Add test**
+
+Create: `backend/tests/test_co_medicaid_payer_id_emits_CO_TXIX.py`:
+
+```python
+"""SP33 regression test: ``PayerConfig.co_medicaid()`` emits CO_TXIX."""
+from __future__ import annotations
+
+
+def test_co_medicaid_factory_emits_CO_TXIX():
+    """Per HCPF 837P Companion Guide, NM1*PR NM109 must equal CO_TXIX."""
+    from cyclone.parsers.payer import PayerConfig
+    cfg = PayerConfig.co_medicaid()
+    assert cfg.payer_id == "CO_TXIX", (
+        f"co_medicaid().payer_id must be 'CO_TXIX' (HCPF guide), got {cfg.payer_id!r}"
+    )
+    assert cfg.payer_name == "CO_TXIX", (
+        f"co_medicaid().payer_name must be 'CO_TXIX' (matches docs/goodclaim.x12), got {cfg.payer_name!r}"
+    )
+```
+
+- [ ] **Step 5: Run the test in the container (since the venv on host isn't trustworthy)**
+
+Run:
+```bash
+docker exec cyclone-backend-1 bash -c "cd /var/lib/cyclone && .venv/bin/pytest tests/test_co_medicaid_payer_id_emits_CO_TXIX.py -v"
+```
+
+Expected: 1 passed.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add backend/src/cyclone/parsers/payer.py backend/tests/test_co_medicaid_payer_id_emits_CO_TXIX.py
+git commit -m "feat(sp33): PayerConfig.co_medicaid() emits CO_TXIX"
+```
+
+## Task 2: Fix `apply_999_rejections` cascade
+
+**Files:**
+- Modify: `backend/src/cyclone/inbox_state.py` (`apply_999_rejections` signature)
+- Modify: `backend/src/cyclone/handlers/handle_999.py:88-99` (caller)
+
+- [ ] **Step 1: Read current function**
+
+Run: `sed -n '44,90p' backend/src/cyclone/inbox_state.py`
+Expected: see `claim = claim_lookup(sr.set_control_number)` at ~line 56.
+
+- [ ] **Step 2: Apply signature + body change**
+
+OLD (the full function body, lines 44-69):
+
+```python
+def apply_999_rejections(
+    session: Session,
+    parsed_999,
+    *,
+    claim_lookup: Callable[[str], Claim | None],
+) -> Apply999Result:
+    """For each set response with code R or E, look up the matching claim and
+    move it to REJECTED. Idempotent on already-rejected claims.
+
+    Args:
+        session: SQLAlchemy session.
+        parsed_999: a ParseResult999 (or any object with .set_responses).
+        claim_lookup: callable from patient_control_number → Claim or None.
+
+    Returns:
+        Apply999Result with lists of matched claim ids and orphan PCNs.
+    """
+    result = Apply999Result()
+    now = datetime.now(timezone.utc)
+
+    for sr in parsed_999.set_responses:
+        code = sr.set_accept_reject.code
+        if code not in ("R", "E", "X"):
+            continue
+
+        claim = claim_lookup(sr.set_control_number)
+        if claim is None:
+            result.orphans.append(sr.set_control_number)
+            continue
+
+        if claim.state == ClaimState.REJECTED:
+            # Idempotent: don't double-mutate.
+            continue
+
+        claim.state = ClaimState.REJECTED
+        claim.state_changed_at = now
+        claim.rejected_at = now
+        claim.rejection_reason = _build_reason(
+            code, len(sr.segment_errors or [])
+        )
+        result.matched.append(claim.id)
+
+    if result.matched or result.orphans:
+        session.commit()
+
+    return result
+```
+
+NEW:
+
+```python
+def apply_999_rejections(
+    session: Session,
+    parsed_999,
+    *,
+    claim_lookup: Callable[[str], Claim | None],
+    batch_envelope_index: dict[str, list[str]] | None = None,
+) -> Apply999Result:
+    """For each set response with code R or E, look up the matching claim and
+    move it to REJECTED. Idempotent on already-rejected claims.
+
+    Args:
+        session: SQLAlchemy session.
+        parsed_999: a ParseResult999 (or any object with .set_responses).
+        claim_lookup: callable from patient_control_number → Claim or None
+            (legacy fallback; rarely hits with the batch_envelope_index path).
+        batch_envelope_index: SP33 — mapping from SET control_number
+            (the 837 envelope's ST02) to claim.id list for claims in that
+            SET. Mirrors apply_999_acceptances so SET-level rejections
+            correctly cascade.
+
+    Returns:
+        Apply999Result with lists of matched claim ids and orphan PCNs.
+    """
+    result = Apply999Result()
+    now = datetime.now(timezone.utc)
+    index = batch_envelope_index or {}
+
+    for sr in parsed_999.set_responses:
+        code = sr.set_accept_reject.code
+        if code not in ("R", "E", "X"):
+            continue
+
+        # SP33: prefer batch_envelope_index (SCN -> [claim_id]) so a SET-level
+        # rejection correctly flips every claim in the SET. Fall back to
+        # the legacy claim_lookup when the index is empty for this SCN.
+        candidate_ids = index.get(sr.set_control_number, []) or []
+        claims_to_reject = []
+        if candidate_ids:
+            claims_to_reject = (
+                session.query(Claim)
+                .filter(Claim.id.in_(candidate_ids))
+                .all()
+            )
+        else:
+            legacy = claim_lookup(sr.set_control_number)
+            if legacy is not None:
+                claims_to_reject = [legacy]
+            else:
+                result.orphans.append(sr.set_control_number)
+                continue
+
+        for claim in claims_to_reject:
+            if claim.state == ClaimState.REJECTED:
+                # Idempotent: don't double-mutate.
+                continue
+            claim.state = ClaimState.REJECTED
+            claim.state_changed_at = now
+            claim.rejected_at = now
+            claim.rejection_reason = _build_reason(
+                code, len(sr.segment_errors or [])
+            )
+            result.matched.append(claim.id)
+
+    if result.matched or result.orphans:
+        session.commit()
+
+    return result
+```
+
+- [ ] **Step 3: Update the caller in handle_999.py**
+
+OLD (line 88):
+
+```python
+        rejection_result = apply_999_rejections(
+            session, result, claim_lookup=_lookup,
+        )
+```
+
+NEW:
+
+```python
+        rejection_result = apply_999_rejections(
+            session, result,
+            claim_lookup=_lookup,
+            batch_envelope_index=batch_index,
+        )
+```
+
+- [ ] **Step 4: Create the cascade test**
+
+Create: `backend/tests/test_apply_999_rejections.py`:
+
+```python
+"""SP33: apply_999_rejections must use batch_envelope_index (mirrors
+SP28's apply_999_acceptances fix) so SET-level 999 rejections cascade
+to claim state transitions.
+"""
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+import pytest
+
+from cyclone.db import Claim, ClaimState
+from cyclone.inbox_state import apply_999_rejections, Apply999Result
+
+
+def _mk_set_response(code: str = "R", scn: str = "991102994"):
+    """Build a stand-in for ParseResult999.set_responses[0]."""
+    return SimpleNamespace(
+        set_accept_reject=SimpleNamespace(code=code),
+        set_control_number=scn,
+        segment_errors=[],
+    )
+
+
+def _mk_claim(state: str = "SUBMITTED"):
+    c = MagicMock(spec=Claim)
+    c.id = "claim-" + state.lower()
+    c.state = state
+    return c
+
+
+def test_set_level_rejection_cascades_via_envelope_index():
+    session = MagicMock()
+    session.query.return_value.filter.return_value.all.return_value = [_mk_claim()]
+
+    parsed = SimpleNamespace(
+        set_responses=[_mk_set_response(code="R", scn="991102994")]
+    )
+    index = {"991102994": ["claim-submitted"]}
+
+    result = apply_999_rejections(
+        session, parsed,
+        claim_lookup=lambda _pcn: None,
+        batch_envelope_index=index,
+    )
+
+    assert len(result.matched) == 1
+    assert result.matched[0] == "claim-submitted"
+    assert result.orphans == []
+    session.commit.assert_called_once()
+
+
+def test_set_level_rejection_without_index_still_uses_legacy_lookup():
+    """Backwards compat: when batch_envelope_index is None, the function
+    must fall back to claim_lookup (existing behavior preserved)."""
+    session = MagicMock()
+    parsed = SimpleNamespace(
+        set_responses=[_mk_set_response(code="R", scn="991102994")]
+    )
+    legacy_claim = _mk_claim()
+    result = apply_999_rejections(
+        session, parsed,
+        claim_lookup=lambda scn: legacy_claim if scn == "991102994" else None,
+    )
+
+    assert result.matched == ["claim-submitted"]
+
+
+def test_no_envelope_index_no_match_becomes_orphan():
+    session = MagicMock()
+    parsed = SimpleNamespace(
+        set_responses=[_mk_set_response(code="R", scn="991102999")]
+    )
+    result = apply_999_rejections(
+        session, parsed,
+        claim_lookup=lambda _pcn: None,
+        batch_envelope_index={},  # empty index
+    )
+    assert result.matched == []
+    assert "991102999" in result.orphans
+
+
+def test_accepted_999_does_not_reject():
+    session = MagicMock()
+    parsed = SimpleNamespace(
+        set_responses=[_mk_set_response(code="A", scn="991102994")]
+    )
+    result = apply_999_rejections(
+        session, parsed,
+        claim_lookup=lambda _pcn: None,
+        batch_envelope_index={"991102994": ["claim-x"]},
+    )
+    assert result.matched == []
+    session.commit.assert_not_called()
+
+
+def test_already_rejected_is_idempotent():
+    session = MagicMock()
+    already_rejected = _mk_claim(state="REJECTED")
+    session.query.return_value.filter.return_value.all.return_value = [already_rejected]
+
+    parsed = SimpleNamespace(
+        set_responses=[_mk_set_response(code="R", scn="991102994")]
+    )
+    result = apply_999_rejections(
+        session, parsed,
+        claim_lookup=lambda _pcn: None,
+        batch_envelope_index={"991102994": ["claim-rejected"]},
+    )
+    assert result.matched == []
+    # nothing was mutated on the already-rejected claim
+    assert already_rejected.state == "REJECTED"
+```
+
+- [ ] **Step 5: Run both test files**
+
+Run:
+```bash
+docker exec cyclone-backend-1 bash -c "cd /var/lib/cyclone && .venv/bin/pytest tests/test_apply_999_rejections.py tests/test_co_medicaid_payer_id_emits_CO_TXIX.py -v"
+```
+
+Expected: 6 passed (1 from Task 1 + 5 from Task 2).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add backend/src/cyclone/inbox_state.py backend/src/cyclone/handlers/handle_999.py backend/tests/test_apply_999_rejections.py
+git commit -m "feat(sp33): apply_999_rejections uses batch_envelope_index"
+```
+
+## Task 3: CLI subcommand `backfill-999-rejections`
+
+**Files:**
+- Modify: `backend/src/cyclone/cli.py` (add subcommand)
+
+- [ ] **Step 1: Locate the cli.py entry point**
+
+Run: `grep -n '@click.command\|def cli\|^@' backend/src/cyclone/cli.py | head -20`
+
+Find an existing subcommand (e.g. `parse-837`) and copy its structure.
+
+- [ ] **Step 2: Add `backfill-999-rejections` subcommand**
+
+Insert after an existing subcommand. The exact insertion point depends on the layout — pick a sensible spot. Use this implementation:
+
+```python
+@click.command(name="backfill-999-rejections")
+@click.option("--dry-run", is_flag=True, default=False,
+              help="Print the would-be changes without writing.")
+@click.option("--actor", default="sp33-backfill",
+              help="Audit log actor for the claim.rejected events.")
+def backfill_999_rejections(dry_run: bool, actor: str):
+    """Replay existing 999 rejections onto already-linked claims.
+
+    SP33. Idempotent — claims already in REJECTED state are skipped.
+
+    Walks claim_acks JOIN acks WHERE set_accept_reject_code='R',
+    then sets claims.state='REJECTED' and fills payer_rejected_* fields.
+    """
+    from sqlalchemy import select
+    from cyclone import db as cycl_db
+    from cyclone.audit_log import AuditEvent, append_event
+    from cyclone.models import Claim as ClaimModel, ClaimAck, Ack
+
+    cycl_db.init_db()
+    with cycl_db.SessionLocal()() as session:
+        rows = session.execute(
+            select(ClaimAck.claim_id, Claim.ack_code, ClaimAck.set_control_number,
+                   ClaimAck.set_accept_reject_code, ClaimAck.ak2_index)
+            .join(Ack, Ack.id == ClaimAck.ack_id)
+            .join(ClaimModel, ClaimModel.id == ClaimAck.claim_id)
+            .where(ClaimAck.set_accept_reject_code == "R")
+        ).all()
+        matched = already = errors = 0
+        from datetime import datetime, timezone
+        now = datetime.now(timezone.utc)
+        for (claim_id, ack_code, scn, arc, ak2_idx) in rows:
+            claim = session.get(ClaimModel, claim_id)
+            if claim is None:
+                errors += 1
+                continue
+            if claim.state == "REJECTED":
+                already += 1
+                continue
+            if not dry_run:
+                claim.state = "REJECTED"
+                claim.state_changed_at = now
+                claim.rejected_at = now
+                claim.rejection_reason = f"999 AK5={ack_code or 'R'} SCN={scn} ak2={ak2_idx}"
+                claim.payer_rejected_at = now
+                claim.payer_rejected_reason = f"999 SET-level reject at SCN={scn}"
+                claim.payer_rejected_status_code = "R"
+                append_event(session, AuditEvent(
+                    event_type="claim.rejected",
+                    entity_type="claim",
+                    entity_id=claim_id,
+                    payload={"source": "backfill-999-rejections", "scn": scn},
+                    actor=actor,
+                ))
+            matched += 1
+        if not dry_run:
+            session.commit()
+        click.echo(
+            f"matched={matched} already_rejected={already} errors={errors} dry_run={dry_run}"
+        )
+```
+
+The exact model class names (`Claim`, `ClaimAck`, `Ack`) and module names (`cyclone.models`, `cyclone.db`, `cyclone.audit_log`) may differ slightly — verify against the existing imports at the top of `cli.py` and adjust.
+
+- [ ] **Step 3: Sanity check (dry-run)**
+
+Run: `docker exec cyclone-backend-1 bash -c "cd /var/lib/cyclone && .venv/bin/python -m cyclone.cli backfill-999-rejections --dry-run"`
+Expected: `matched=338 already_rejected=0 errors=0 dry_run=True` (or similar; the exact number depends on how many unique claim_ids have R-coded links).
+
+- [ ] **Step 4: Run for real**
+
+Run: `docker exec cyclone-backend-1 bash -c "cd /var/lib/cyclone && .venv/bin/python -m cyclone.cli backfill-999-rejections"`
+Expected: `matched=338 already_rejected=0 errors=0 dry_run=False`.
+
+- [ ] **Step 5: Verify claim states flipped in the DB**
+
+Run:
+```bash
+docker exec cyclone-backend-1 python3 -c "
+import sqlite3
+conn = sqlite3.connect('/var/lib/cyclone/db/cyclone.db')
+cur = conn.cursor()
+cur.execute('SELECT state, count(*) FROM claims GROUP BY state ORDER BY 2 DESC')
+for row in cur.fetchall(): print(row)
+"
+```
+
+Expected: `('REJECTED', 341)` and `('SUBMITTED', 334)` (338 newly-rejected + the 3 pre-existing rejected = 341; original 672 minus 338 = 334).
+
+- [ ] **Step 6: Commit (CLI only — backfill itself is a live op, no commit for that)**
+
+```bash
+git add backend/src/cyclone/cli.py
+git commit -m "feat(sp33): cli backfill-999-rejections"
+```
+
+## Task 4: CLI subcommand `resubmit-rejected-claims`
+
+**Files:**
+- Modify: `backend/src/cyclone/cli.py` (add subcommand)
+
+- [ ] **Step 1: Add `resubmit-rejected-claims` subcommand**
+
+```python
+@click.command(name="resubmit-rejected-claims")
+@click.option("--payer", default="co_medicaid",
+              help="Payer factory key (default: co_medicaid).")
+@click.option("--ingest-dir", default="/home/tyler/dev/cyclone/ingest",
+              help="Directory holding batch-*-claims/ subfolders (per Tyler's split).")
+@click.option("--actor", default="sp33-resubmit",
+              help="Audit log actor for the clearhouse.submitted events.")
+@click.option("--dry-run", is_flag=True, default=False,
+              help="Replace + validate but do not upload.")
+def resubmit_rejected_claims(payer: str, ingest_dir: str, actor: str, dry_run: bool):
+    """Byte-level SKCO0->CO_TXIX fix + SFTP resubmit of rejected claims.
+
+    SP33. For each claims row in REJECTED state, locate the matching single-
+    claim 837 file in ingest_dir/batch-<batch_id>-<N>-claims/*.x12, replace
+    PI*SKCO0 with PI*CO_TXIX in the bytes, validate via parse_837_text, then
+    upload via SftpClient. Idempotent per claim (resubmit_count gates re-run).
+    """
+    from pathlib import Path
+    import glob
+    from cyclone import db as cycl_db
+    from cyclone.audit_log import AuditEvent, append_event
+    from cyclone.clearhouse import SftpClient
+    from cyclone.parsers.parse_837 import parse_837_text
+
+    cycl_db.init_db()
+    upload_root = "/CO XIX/PROD/coxix_prod_11525703/ToHPE"
+
+    # 1. collect rejected claims
+    with cycl_db.SessionLocal()() as session:
+        from sqlalchemy import select
+        from cyclone.models import Claim as ClaimModel
+        rows = session.execute(
+            select(ClaimModel.id, ClaimModel.batch_id, ClaimModel.patient_control_number,
+                   ClaimModel.resubmit_count, ClaimModel.charge_amount)
+            .where(ClaimModel.state == "REJECTED")
+            .order_by(ClaimModel.batch_id, ClaimModel.id)
+        ).all()
+
+        # 2. discover candidate files
+        files_by_batch = {}
+        for batch_dir in glob.glob(os.path.join(ingest_dir, "batch-*-*-claims")):
+            batch_id = os.path.basename(batch_dir).split("-")[1]  # batch-<id>-<N>-claims
+            files_by_batch[batch_id] = sorted(glob.glob(os.path.join(batch_dir, "*.x12")))
+
+        ok = err = skip = 0
+        for (cid, bid, pcn, prev_resub, charge) in rows:
+            if prev_resub and prev_resub > 0:
+                skip += 1; continue
+
+            candidate_files = files_by_batch.get(bid, [])
+            # Find the file whose CLM01 == this claim's pcn
+            target_path = None
+            for fp in candidate_files:
+                with open(fp, "rb") as fh:
+                    txt = fh.read().decode("ascii", errors="replace")
+                if pcn in txt:
+                    target_path = fp
+                    break
+            if target_path is None:
+                click.echo(f"  no-file  claim={cid} pcn={pcn}", err=True)
+                err += 1
+                continue
+
+            # Byte-level fix
+            with open(target_path, "rb") as fh:
+                raw = fh.read()
+            if b"PI*SKCO0" not in raw:
+                click.echo(f"  no-replace  claim={cid} file={os.path.basename(target_path)}", err=True)
+                err += 1; continue
+            fixed = raw.replace(b"PI*SKCO0", b"PI*CO_TXIX")
+
+            # Validate
+            try:
+                parsed = parse_837_text(fixed.decode("ascii"))
+            except Exception as exc:
+                click.echo(f"  parse-fail  claim={cid} {exc.__class__.__name__}: {exc}", err=True)
+                err += 1; continue
+
+            # Upload
+            remote_name = os.path.basename(target_path)
+            if not dry_run:
+                # Write the fixed bytes to a sibling tmp file for the upload
+                tmp_path = target_path + ".fixed"
+                with open(tmp_path, "wb") as fh:
+                    fh.write(fixed)
+                try:
+                    SftpClient().put(tmp_path, f"{upload_root}/{remote_name}")
+                finally:
+                    os.unlink(tmp_path)
+                claim = session.get(ClaimModel, cid)
+                claim.resubmit_count = (claim.resubmit_count or 0) + 1
+                append_event(session, AuditEvent(
+                    event_type="clearhouse.submitted",
+                    entity_type="claim",
+                    entity_id=cid,
+                    payload={"file": remote_name, "scn": parsed.envelope.control_number},
+                    actor=actor,
+                ))
+                session.commit()
+            click.echo(f"  ok  claim={cid} file={remote_name}")
+            ok += 1
+
+        click.echo(f"\nDONE ok={ok} err={err} skip={skip} dry_run={dry_run}")
+```
+
+Imports needed: `import os` (glob, path). Confirm the `SftpClient` constructor — it may take an SFTP block or a config; check existing usage in `backend/src/cyclone/api.py` (the `/api/clearhouse/submit` endpoint) and mirror it.
+
+- [ ] **Step 2: Run with --dry-run first**
+
+Run: `docker exec cyclone-backend-1 bash -c "cd /var/lib/cyclone && CYCLONE_INGEST_DIR=/tmp/ingest_passthrough .venv/bin/python -m cyclone.cli resubmit-rejected-claims --dry-run"`
+Expected: a line per claim plus a `DONE ok=338 err=0 skip=0 dry_run=True` summary.
+
+- [ ] **Step 3: Run for real (upload)**
+
+Mount /home/tyler/dev/cyclone/ingest into the container so the `--ingest-dir` resolves correctly. Easiest: copy the batch-* subdirs into the container:
+
+```bash
+docker exec cyclone-backend-1 mkdir -p /tmp/ingest_split
+tar -C /home/tyler/dev/cyclone/ingest -cf - 'batch-*-*-claims' | docker exec -i cyclone-backend-1 tar -xf - -C /tmp/ingest_split
+```
+
+Then: `docker exec cyclone-backend-1 bash -c "cd /var/lib/cyclone && .venv/bin/python -m cyclone.cli resubmit-rejected-claims --ingest-dir /tmp/ingest_split"`
+
+Expected: `DONE ok=338 err=0 skip=0 dry_run=False`.
+
+- [ ] **Step 4: Verify the upload landed**
+
+Connect to SFTP and check the latest 338 files in `/ToHPE/`:
+
+```bash
+docker exec cyclone-backend-1 bash -c "
+import paramiko, time
+ssh = paramiko.SSHClient(); ssh.set_missing_host_key_policy(paramiko.AutoAddPolicy())
+ssh.connect('mft.gainwelltechnologies.com', username='colorado-fts\\\\coxix_prod_11525703',
+            password=\$(cat /run/secrets/cyclone_sftp_password))
+sftp = ssh.open_sftp()
+files = sorted(sftp.listdir_attr('/CO XIX/PROD/coxix_prod_11525703/ToHPE'),
+               key=lambda a: a.st_mtime)[-10:]
+for f in files: print(f.filename, time.ctime(f.st_mtime))
+"
+```
+
+Expected: ~10 837P files dated 2026-07-02 (or now).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add backend/src/cyclone/cli.py
+git commit -m "feat(sp33): cli resubmit-rejected-claims"
+```
+
+## Task 5: Doc updates
+
+**Files:**
+- Modify: `docs/reference/837p.md:48`
+- Modify: `docs/reference/co-medicaid.md:118`
+
+- [ ] **Step 1: Update `docs/reference/837p.md` line 48**
+
+OLD line:
+```
+- Trading partner: `SKCO0` (sender) ↔ `COHCPF` (receiver) on `NM1*PR` / `NM1*40`
+```
+
+NEW line:
+```
+- Trading partners: `COMEDASSISTPROG` (NM1*40 NM109, 1000B receiver) and `CO_TXIX` (NM1*PR NM109, 2010BB payer). See `docs/goodclaim.x12` for a canonical example and the HCPF 837P Companion Guide for the full segment table.
+```
+
+- [ ] **Step 2: Update `docs/reference/co-medicaid.md` line 118**
+
+OLD:
+```
+- `NM1*PR N104 = "SKCO0"` (COHCPF)
+```
+
+NEW:
+```
+- `NM1*PR NM108 = "PI"`, `NM1*PR NM109 = "CO_TXIX"` (per HCPF 837P Companion Guide, June 2025 — Version 2.5). dzinesco submits against this code under dzinesco TPID `11525703`. The legacy trading-partner ID `SKCO0` is no longer accepted as the payer identifier.
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add docs/reference/837p.md docs/reference/co-medicaid.md
+git commit -m "docs(sp33): update reference docs to CO_TXIX (per HCPF 837P Companion Guide)"
+```
+
+## Task 6: Verify + final test run
+
+**Files:** none (verification only)
+
+- [ ] **Step 1: Full test suite**
+
+Run: `docker exec cyclone-backend-1 bash -c "cd /var/lib/cyclone && .venv/bin/pytest -x -q"`
+Expected: all tests pass. The 4 affected test files (this plan + Spec §6 list) all green.
+
+- [ ] **Step 2: Smoke-test the live DB dashboard widget**
+
+Run:
+```bash
+curl -fsS http://localhost:8000/api/batches | python3 -m json.tool | head -30
+```
+
+Expected: the dashboard reflects the freshly-REJECTED batches (acceptedCount=0 for the 4 affected batches — this is now correct! They were rejected by Gainwell, and the cascade now shows that).
+
+- [ ] **Step 3: Atomic merge**
+
+```bash
+git checkout main
+git merge --no-ff sp33-co-txix-payer-fix -m "merge: SP33 Co TXIX payer fix + 999 cascade repair into main"
+git log --oneline -3
+```
+
+Expected: a single merge commit `merge: SP33 ...` on top of `dfd6542` (current main tip pre-SP33), with the SP33 branch's commits visible as parents.
+
+## Acceptance checklist (must all be true before claiming "done")
+
+- [ ] `cyclone -m cyclone.cli backfill-999-rejections` reports `matched=338 already_rejected=0 errors=0`
+- [ ] `claims.state` count: REJECTED ≥ 341, SUBMITTED ≤ 334
+- [ ] 338 new 837 files visible on SFTP `/CO XIX/PROD/cox17_prod_11525703/ToHPE/` with `CO_TXIX` in their bytes
+- [ ] `claims.resubmit_count > 0` for the 338 claims
+- [ ] `audit_log` shows 338 `claim.rejected` + 338 `clearhouse.submitted` events with actor=`sp33-*`
+- [ ] Dashboard "Recent batches" widget for the 4 affected batches shows the same `acceptedCount` it was showing — but now it's accurate (0 rejected by Gainwell, not 0 accepted by Gainwell)
+
+## Rollback
+
+If anything breaks and SP33 needs to back out:
+
+1. `git revert -m 1 <merge-sha>` on `main` — produces a fresh revert commit, preserves history.
+2. The 2 cli subcommands revert cleanly (pure additions).
+3. To un-reject the 338 claims after the revert, run a sister SQL: `UPDATE claims SET state='SUBMITTED', rejection_reason=NULL, rejected_at=NULL, payer_rejected_at=NULL, payer_rejected_reason=NULL, payer_rejected_status_code=NULL WHERE resubmit_count > 0;`
+4. The 338 837 files already on SFTP /ToHPE/ cannot be unsent — Gainwell will pick them up regardless. Discretion required.