cyclone/docs/superpowers/specs/2026-07-08-cyclone-reissue-claims-design.md

Sub-project 24 — Reissue Claims CLI + IG-Correctness Regression Test: Design Spec

Date: 2026-07-08 Status: Draft, awaiting user sign-off Branch: sp24-reissue-claims Aesthetic direction: No new UI (operator-only CLI; the workflow is the on-call page already documented in docs/RUNBOOK.md).

1. Scope

On 2026-07-08 the operator rebuilt the four dzinesco July-8 837P batches into 358 single-claim, IG-correct X12 files (zipped at /home/tyler/dev/cyclone/xxxclaims.zip) using a one-shot script at scripts/reissue_claims.py. The script solved an immediate crisis: an Edifabric 999 had rejected the original four multi-claim files because the serializer was unconditionally emitting the Loop 2000C patient hierarchy (HL*3 → PAT*01 → NM1*QC) when SBR02 == "18" (Self-pay), which is forbidden by X12 005010X222A1.

The serializer default was fixed in serialize_837.py (see commit ee1a397 on sp41-inwindow-rebill-pipeline), but the workflow that proved the fix — parse + per-claim re-serialize + HCPF-spec filename + zip — still lives in a script the rest of the cyclone pipeline doesn't know about. SP24 brings that workflow into the canonical CLI surface as cyclone reissue-claims, behind a regression test that locks in the IG-correct serializer default forever so a future code change cannot silently reintroduce the same 999 rejection.

In scope:

• A new subpackage backend/src/cyclone/reissue/ containing the pure functions parse_inputs, emit_outputs, zip_outputs, and ig_correctness_check. No Click imports inside the core module — it accepts plain Python types so the CLI is a thin wrapper and the functions are unit-testable without click.testing.CliRunner.
• A new CLI subcommand cyclone reissue-claims registered against the existing @main Click group in backend/src/cyclone/cli.py, following the conventions in cyclone-cli (long-form flags, exit codes 0/1/2, click.echo(..., err=True) for errors).
• A new module-level public constant in serialize_837.py: PATIENT_LOOP_DEFAULT_INCLUDED = False, exported in the module's __all__. The default is read by the IG-correctness guard instead of inspect.signature-ing a private helper, so a future rename of _build_subscriber_block cannot silently break the guard.
• A regression test test_serialize_837_patient_loop_default_is_false in backend/tests/test_serialize_837.py that asserts the constant is False and that calling _build_subscriber_block with no include_patient_loop kwarg emits HL*2 child_count=0 (no HL*3).
• Smoke tests under backend/tests/test_cli_reissue_claims.py covering the help screen, an empty-input path, a happy-path re-issue, and the IG-correctness guard firing when the constant is monkeypatched.
• Pure-unit tests under backend/tests/test_reissue_core.py covering parse_inputs (AppleDouble filter, per-file failure tolerance), emit_outputs (HCPF-spec filenames, unique-per-millisecond, sorted by claim_id), zip_outputs (round-trip integrity check), and ig_correctness_check (fires on mismatch, silent on match).
• A deprecation shim at scripts/reissue_claims.py that re-exports the new CLI subcommand as a thin wrapper with a WARNING printed at import time telling the operator cyclone reissue-claims is the canonical entry. The shim is removed in a follow-up increment.
• A docs/RUNBOOK.md entry under "Operator workflows" pointing at the new CLI subcommand with a worked example against the dzinesco July-8 billing layout.

Out of scope:

• New UI exposure for the reissue workflow. The CLI is the operator's on-call surface today; a dashboard widget is a future increment.
• A bulk-ingest pipeline for the reissue path. The operator's flow is point-in-time ("rebuild yesterday's 358 files from this batch"), not a streaming one. cyclone bulk-ingest already handles the streaming case for inbound files; the outbound reissue path stays explicit.
• The SFTP-upload step. reissue-claims writes files to a local directory (and optionally zips them). The operator moves the resulting zip to Gainwell via their SFTP client per the "Manual SFTP mode" posture documented in docs/RUNBOOK.md.
• An automatic regeneration of historical files. The four dzinesco July-8 batches are the immediate operator concern; running reissue-claims against older batches is a deliberate operator action with the explicit --input-dir path.
• Edifabric validation. The original script did not gate through Edifabric (the July-8 files were validated by the operator's manual 999 audit). A follow-up SP wires the SP41 SP40 Edifabric gate into the reissue path; this increment keeps the surface minimal.

2. Decisions (locked during brainstorming)

1. Subpackage layout, not a single cli.py block. The other cross-cutting workflows (cyclone.rebill, cyclone.submission, cyclone.bulk_ingest) follow the cyclone/<verb>/ layout. Putting the reissue logic inside cli.py directly — like rebill-from-835 does — would make cli.py grow past 2,200 LOC (already at 2,054) and force the unit tests to live in the CLI-flavored test_cli_*.py file. The subpackage layout keeps the pure functions unit-testable without Click, matches the rest of the codebase, and lets cli.py stay a thin registration surface.

2. Public PATIENT_LOOP_DEFAULT_INCLUDED constant, not inspect.signature introspection. The original script introspected the private _build_subscriber_block helper via inspect.signature, which is fragile against rename / refactor. Promoting the default to a named public constant in serialize_837.py and exporting it in __all__ gives the guard a stable handle that survives any future refactor of the helper.

3. cyclone reissue-claims long-form CLI flags. --input-dir, --output-root, --date, --pipeline, --payer, --sender-id, --receiver-id, --submitter-name, --submitter-contact-name, --submitter-contact-email, --receiver-name, --zip-output, --no-clean, --log-level. Long-form, not positional, so the destructive surface is self-documenting. Defaults match the dzinesco canonical sender (11525703) / receiver (COMEDASSISTPROG) so the typical invocation is just cyclone reissue-claims --input-dir <batch>.

4. IG-correctness guard fires on every CLI invocation. Not gated behind a --strict flag — the constant is part of the canonical contract the spec requires. The guard's only job is to fail loud if the constant flips to True in a future refactor; running it on every call is the cheapest possible regression test.

5. Exit codes 0 / 1 / 2 mirror the existing CLI conventions. 0 = success (all files written, zip optional); 1 = IG-correctness guard tripped OR a configuration / unexpected error; 2 = parse / validation failure on a file (per-file failures reported in stdout, but other files continue; only exits 2 if zero claims survived).

6. Deprecation shim, not deletion. The original scripts/reissue_claims.py stays as a 1-line shim that prints a WARNING at import time and re-exports the new module's main() function. The shim is removed in a follow-up increment once the operator's muscle memory has switched over.

7. The CLI subcommand does NOT call cyclone.submission.submit_file. Reissue is an offline-rebuild workflow; it produces local X12 files for the operator to inspect / upload manually. Wiring the SFTP path would conflate "regenerate clean files" with "submit them to Gainwell", and the operator wants the inspection step in between.

8. HCPF-spec filename unchanged. The canonical cyclone.edi.filenames.build_outbound_filename(sender_id, "837P") produces the file names already in use (tp11525703-837P-...-1of1.x12); no change to the filename format. Per-claim 1 ms timestamp offsets (via datetime.now(tz=ZoneInfo("America/Denver")) + per-claim timedelta(milliseconds=i)) guarantee uniqueness within a batch.

3. Threat model

This increment does not change the auth boundary or the network posture. The threat model is unchanged from SP24 (this spec): the auth boundary is HTTP (login required, bcrypt + HttpOnly session cookie); the file-system threat is local-only and handled by SQLCipher at rest and the macOS Keychain. The CLI subcommand runs against the operator's local environment only — there is no HTTP surface, no auth gate, no network call. The IG-correctness guard is a static check against the serializer's documented default; it does not change the security posture.

The regression test in test_serialize_837.py is structural: it pins a constant to a specific value. If a future refactor flips the constant back to True (the broken pattern), the test fails, the CLI guard fires, and the operator sees a clear REFUSING to run log line before any X12 byte is emitted.

4. Test impact

Following the cyclone-tests conventions:

• Unit tests (pure-unit):
  • backend/tests/test_reissue_core.py — covers parse_inputs (AppleDouble metadata filter, per-file failure tolerance, claim validation error path), emit_outputs (HCPF-spec filename format, sorted by claim_id, per-claim unique timestamps, directory creation), zip_outputs (round-trip integrity via testzip()), and ig_correctness_check (fires on mismatch, silent on match). Each test uses tmp_path + a fixture *.x12 file containing a minimal valid 837P — no prodfiles dropped into fixtures/.
  • backend/tests/test_serialize_837.py — adds test_serialize_837_patient_loop_default_is_false asserting that serialize_837.PATIENT_LOOP_DEFAULT_INCLUDED is False and that calling _build_subscriber_block with no kwargs emits HL*2 with child_count = 0 (no HL*3). This test is the long-term regression guard; flipping it should require an explicit PR-level discussion.
• Integration tests (CLI smoke):
  • backend/tests/test_cli_reissue_claims.py — CliRunner-based smoke tests for cyclone reissue-claims. Covers:
    • --help exits 0 with the expected long-form flags listed.
    • happy path: a single-file input dir produces the expected number of output files under tmp_path/out.
    • empty input dir: exits 2 with a clear "no claims found" message.
    • IG-correctness guard: monkeypatches serialize_837.PATIENT_LOOP_DEFAULT_INCLUDED to True, asserts the CLI exits 1 with the REFUSING to run log line in the captured stderr.
• Fixture additions: none. The CLI smoke test synthesizes a minimal 837P file inline via parse_837 round-tripping a stub ClaimOutput. No prodfiles are dropped into fixtures/.
• Frontend tests: none (no UI in this increment).
• Live-test smoke: a canonical end-to-end run against /home/tyler/dev/cyclone/july8billing/ to confirm the CLI produces the same 358 files + zip as the original script. The smoke command is documented at the top of /tmp/refactor-cyclone.md.

5. Spec & plan anchors

• Spec anchor (this file): docs/superpowers/specs/2026-07-08-cyclone-reissue-claims-design.md
• Plan anchor: docs/superpowers/plans/2026-07-08-cyclone-reissue-claims.md
• Related serializer fix: commit ee1a397 on sp41-inwindow-rebill-pipeline (already merged to main), which flipped the _build_subscriber_block.include_patient_loop default from True to False and updated the docstring.
• Original operator workflow: scripts/reissue_claims.py (the one-shot script this increment supersedes).
• Edifabric 999 that surfaced the bug: /tmp/ig_check.log (the operator's 999 audit reference for the IG rule).

6. Acceptance criteria

1. cyclone reissue-claims --help exits 0 and lists the long-form flags listed in §2 Decision 3.
2. cyclone reissue-claims --input-dir /home/tyler/dev/cyclone/july8billing --date 2026-07-08 --output-root /tmp/sp24-acceptance-out produces exactly 358 .x12 files under /tmp/sp24-acceptance-out/2026-07-08/initial/, plus a _serialize_summary.json sidecar with one row per file.
3. cyclone reissue-claims --input-dir ... --zip-output /tmp/sp24-acceptance.zip produces a zip whose testzip() returns None (integrity OK) and which contains exactly 358 entries.
4. The IG-correctness guard exits 1 with the REFUSING to run log line when the constant is monkeypatched to True. Verified by the test_cli_reissue_claims.py smoke test.
5. pytest backend/tests/test_reissue_core.py -v exits 0 with all cases passing.
6. pytest backend/tests/test_cli_reissue_claims.py -v exits 0 with all cases passing.
7. pytest backend/tests/test_serialize_837.py -v exits 0 with the new test_serialize_837_patient_loop_default_is_false case passing alongside the existing 56 cases.
8. pytest (full backend suite) exits 0; no regressions.
9. The CLI runs without requiring a Keychain entry or DB connection — reissue-claims is a pure parser + serializer + filesystem workflow. This matches the original script's posture.
10. After the merge to main, scripts/reissue_claims.py is a 1-line shim that prints a WARNING at import time telling the operator cyclone reissue-claims is the canonical entry. The shim does NOT duplicate the argparse surface.