From a8aef7b9b25c8d4c0ade6b6acc9584c47102d82f Mon Sep 17 00:00:00 2001
From: Nora <nora_rocks@agentmail.to>
Date: Wed, 8 Jul 2026 22:37:38 -0600
Subject: [PATCH] docs(sp24): RUNBOOK entry for cyclone reissue-claims

Adds a 'Reissue claims (SP24)' section under the Manual SFTP mode
heading, pointing the operator at the new CLI subcommand with a
worked example against the dzinesco July-8 billing layout.

Covers:
  - the canonical command (full flag set, full output path)
  - the 5-step workflow (parse / validate / serialize / write / zip)
  - the exit-code contract (0/1/2)
  - the IG-correctness guard's purpose + the regression story
  - the 'no SFTP' boundary so the operator doesn't expect this
    to push files to Gainwell (use submit-batch for that)
---
 docs/RUNBOOK.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/docs/RUNBOOK.md b/docs/RUNBOOK.md
index f8f3edf..df75319 100644
--- a/docs/RUNBOOK.md
+++ b/docs/RUNBOOK.md
@@ -233,6 +233,53 @@ sorted, with `._*` AppleDouble files skipped.
 - CLI exit 0 on completed runs (per-file failures counted, not bumped);
   2 on config-level failures (no clearhouse / stub mode / missing dir).
 
+### Reissue claims (SP24)
+
+For rebuilding raw 837P files into one IG-correct single-claim X12
+file per claim — e.g. after a 999 rejection that surfaced an
+in-scope serializer defect — use `cyclone reissue-claims`. This is
+the canonical offline-rebuild workflow; the pre-SP24 script
+`scripts/reissue_claims.py` is a deprecation shim that prints a
+warning at import time.
+
+```bash
+cd /home/tyler/dev/cyclone/backend
+.venv/bin/python -m cyclone.cli reissue-claims \
+    --input-dir /home/tyler/dev/cyclone/july8billing \
+    --date 2026-07-08 \
+    --output-root /home/tyler/dev/cyclone/dev/rebills \
+    --pipeline initial \
+    --zip-output xxxclaims.zip
+```
+
+What it does:
+
+1. Parse every `*.x12` / `*.txt` / `*.edi` under `--input-dir`.
+2. Validate each parsed claim; skip claims with hard errors.
+3. Serialize each surviving claim via the IG-correct serializer
+   (no `HL*3` / `PAT` / `NM1*QC` when `SBR02 == "18"`).
+4. Write one X12 per claim under
+   `--output-root/<date>/<pipeline>/` with HCPF-spec filenames.
+5. Optionally zip the output to `--zip-output`.
+
+**Exit codes:** 0 success (per-file warnings are non-fatal); 1
+IG-correctness guard tripped (the serializer's `PATIENT_LOOP_DEFAULT_INCLUDED`
+constant is `True`) or unexpected error; 2 parse / validation failure
+on a file AND zero claims survived.
+
+**IG-correctness guard.** On every invocation the CLI refuses to run
+if the serializer's default has been flipped back to `True`. This is
+the SP24 regression guard — flipping the constant would re-introduce
+the 2026-07-08 Edifabric 999 rejection ("2000C HL must be absent
+when 2000B SBR02 = '18'"). The guard's only job is to fail loud; it
+runs once per invocation and reads one module-level constant.
+
+**No SFTP.** `reissue-claims` is a pure local workflow — no DB write,
+no SFTP upload, no Edifabric gate. To push the rebuilt files to
+Gainwell, use `cyclone submit-batch --ingest-dir <the emitted dir>`
+(see the "Submitting claims" section above) or move the zip manually
+per the "Manual SFTP mode" posture.
+
 ### Note on per-file parse CLIs
 
 `parse-837` and `parse-835` exist as CLIs but only emit JSON files to