docs: surface SP9-SP13 in README + endpoint reference #1

2026-06-21T00:19:49-06:00

tyler commented

2026-06-21 00:19:49 -06:00

What

Bring the README back in line with the codebase. The root README only documented up to SP8 even though SP9-SP13 (multi-payer + multi-NPI + SFTP stub, 277CA + Payer-Rejected lane, tamper-evident audit log, optional SQLCipher encryption, paramiko SFTP wire-up) are all merged into main.

Changes

Inbox

Bump lane count from four to five.
Add the new Payer-rejected lane (claims whose 277CA STC category is A4/A6/A7). Stamped at 277CA ingest, monotonic, never overwritten by a looser later 277CA.

New top-level sections

Multi-Payer, Multi-NPI & Clearhouse (SP9) — providers / payers / payer_configs / clearhouse tables, config/payers.yaml loader, the config + clearhouse endpoint table.
277CA Claim Acknowledgment (SP10) — POST /api/parse-277ca, GET /api/277ca-acks[/...], monotonic payer-rejection stamp contract.
Tamper-Evident Audit Log (SP11) — hash-chained audit_log, GET /api/admin/audit-log/verify chain walker.
Encryption at Rest (SP12) — Keychain-stored SQLCipher key, transparent fallback to plain SQLite, link to the Keychain setup recipe in docs/reference/co-medicaid.md.
SFTP Wire-Up (paramiko, SP13) — production submit path, file-naming template, Keychain-stored SFTP credential.

Persistence

Bump the lead paragraph to mention 277CA rejections, hash-chained audit log entries, SFTP submission history. Link to the new Encryption at Rest section.

Roadmap

Bump shipped sub-projects from 2-8 to 2-13. Add a one-line pointer to the 2026-06-20 completeness review for the honest industry-gap accounting. Add a SP9-SP13 quick-summary at the top of the shipped list.
Update SP3 endpoint list to include parse-ta1 + ta1-acks.
Update SP6 endpoint list to reference five lanes.
Add SP9-SP13 endpoint reference sections at the end of the Roadmap.

Project layout

Add the new backend modules: api_helpers, db, db_migrate, db_crypto, audit_log, inbox_lanes, inbox_state, inbox_state_277ca, providers, payers, secrets, reconcile.
Add config/payers.yaml, docs/reviews/, and the new docs/superpowers/specs/ tree.
Add the new test files.

backend/README.md

Refresh the endpoint table to include parse-999, parse-ta1, parse-277ca, eligibility/request, eligibility/parse-271, clearhouse, clearhouse/submit, admin/reload-config, admin/audit-log, admin/audit-log/verify. Point at the root README for the full route list.

Verification

pytest --collect-only in backend/ collects 733 tests (the suite has grown past the 574 reported in the 2026-06-20 review).
git diff --check clean.
Section structure: 12 new ## top-level sections added; existing sections preserved.

Out of scope

There is a separate, unrelated refactor in the working tree (the api.py → api_helpers.py split) that I deliberately did NOT include in this PR. That belongs in its own PR.

## What Bring the README back in line with the codebase. The root README only documented up to SP8 even though SP9-SP13 (multi-payer + multi-NPI + SFTP stub, 277CA + Payer-Rejected lane, tamper-evident audit log, optional SQLCipher encryption, paramiko SFTP wire-up) are all merged into main. ## Changes **Inbox** - Bump lane count from four to five. - Add the new **Payer-rejected** lane (claims whose 277CA STC category is A4/A6/A7). Stamped at 277CA ingest, monotonic, never overwritten by a looser later 277CA. **New top-level sections** - **Multi-Payer, Multi-NPI & Clearhouse (SP9)** — `providers` / `payers` / `payer_configs` / `clearhouse` tables, `config/payers.yaml` loader, the config + clearhouse endpoint table. - **277CA Claim Acknowledgment (SP10)** — `POST /api/parse-277ca`, `GET /api/277ca-acks[/...]`, monotonic payer-rejection stamp contract. - **Tamper-Evident Audit Log (SP11)** — hash-chained `audit_log`, `GET /api/admin/audit-log/verify` chain walker. - **Encryption at Rest (SP12)** — Keychain-stored SQLCipher key, transparent fallback to plain SQLite, link to the Keychain setup recipe in `docs/reference/co-medicaid.md`. - **SFTP Wire-Up (paramiko, SP13)** — production submit path, file-naming template, Keychain-stored SFTP credential. **Persistence** - Bump the lead paragraph to mention 277CA rejections, hash-chained audit log entries, SFTP submission history. Link to the new Encryption at Rest section. **Roadmap** - Bump shipped sub-projects from 2-8 to 2-13. Add a one-line pointer to the 2026-06-20 completeness review for the honest industry-gap accounting. Add a SP9-SP13 quick-summary at the top of the shipped list. - Update SP3 endpoint list to include `parse-ta1` + `ta1-acks`. - Update SP6 endpoint list to reference five lanes. - Add SP9-SP13 endpoint reference sections at the end of the Roadmap. **Project layout** - Add the new backend modules: `api_helpers`, `db`, `db_migrate`, `db_crypto`, `audit_log`, `inbox_lanes`, `inbox_state`, `inbox_state_277ca`, `providers`, `payers`, `secrets`, `reconcile`. - Add `config/payers.yaml`, `docs/reviews/`, and the new `docs/superpowers/specs/` tree. - Add the new test files. **backend/README.md** - Refresh the endpoint table to include `parse-999`, `parse-ta1`, `parse-277ca`, `eligibility/request`, `eligibility/parse-271`, `clearhouse`, `clearhouse/submit`, `admin/reload-config`, `admin/audit-log`, `admin/audit-log/verify`. Point at the root README for the full route list. ## Verification - `pytest --collect-only` in `backend/` collects **733 tests** (the suite has grown past the 574 reported in the 2026-06-20 review). - `git diff --check` clean. - Section structure: 12 new `## ` top-level sections added; existing sections preserved. ## Out of scope There is a separate, unrelated refactor in the working tree (the `api.py` → `api_helpers.py` split) that I deliberately did NOT include in this PR. That belongs in its own PR.

tyler added 1 commit 2026-06-21 00:19:49 -06:00

docs: surface SP9-SP13 in README + endpoint reference 63b2870f6e

The README only documented up to SP8 even though SP9-SP13 (multi-payer
+ multi-NPI + SFTP stub, 277CA + Payer-Rejected lane, tamper-evident
audit log, optional SQLCipher encryption, paramiko SFTP wire-up) are
all merged into main.

This brings the README back in line with the codebase:

- Inbox section: bump lane count from four to five, add the
  payer_rejected lane (and its monotonic stamping contract).
- Add a Multi-Payer, Multi-NPI & Clearhouse section (SP9): the
  providers / payers / payer_configs / clearhouse tables, the
  config/payers.yaml loader, the new config + clearhouse endpoints.
- Add a 277CA Claim Acknowledgment section (SP10): parse-277ca +
  277ca-acks, the Payer-Rejected stamp semantics.
- Add a Tamper-Evident Audit Log section (SP11): hash-chained
  audit_log, the verify endpoint.
- Add an Encryption at Rest section (SP12): Keychain-stored
  SQLCipher key, transparent fallback to plain SQLite.
- Add an SFTP Wire-Up (paramiko) section (SP13): the production
  submit path and the file-naming template.
- Persistence section: link to the Encryption at Rest section.
- Roadmap: bump shipped sub-projects to 2-13, add a one-line
  pointer to the completeness review for the honest industry-gap
  accounting.
- Project layout: add api_helpers, db_crypto, audit_log, the new
  inbox_* modules, providers/payers/secrets, the new test files,
  and the config/ + docs/reviews/ + docs/superpowers/specs/ tree.
- backend/README: refresh the endpoint table to include the
  parse-999/parse-ta1/parse-277ca/eligibility/clearhouse/admin
  surface; point at the root README for the full route list.

tyler closed this pull request

2026-06-21 01:06:12 -06:00

tyler referenced this pull request

2026-06-21 01:08:01 -06:00

docs: surface SP14 (Payer-Rejected UI + acknowledge) + SP15 (key rotation) #2

tyler referenced this pull request

2026-06-21 01:10:44 -06:00

docs: surface SP14 (Payer-Rejected UI + acknowledge) + SP15 (key rotation) #3

tyler referenced this issue from a commit

2026-07-07 12:26:35 -06:00

fix(sp37-followup): remove dead /api/resubmit permissions entry