healthcare: two-tier (standard paper / expedited surrogate) filing model
- Verified Standard(no-login)/Expedited(surrogate) matrix from official CMS-855 PDFs (docs/healthcare-filing-tiers-verified.md): reactivation+revalidation are 855I paper-to-MAC reasons, original-signature, routed by state; sig may not be delegated; 855B needs PECOS app fee. - Add scripts/workers/mac_routing.py: state->MAC routing (all 56 jurisdictions, 12 destinations) for envelope addressing + daily batch grouping. Addresses marked VERIFY before live mail. - npi_provider.py: fix access strings to two-tier framing; NPPES update/reactivation no longer 'online-only'; note 855B fee. - checkout.ts + service pages: strip client-facing mechanics & the paper-vs-tier choice; surrogate is the only optional, positively-framed ask (faster, never required, never share password).
This commit is contained in:
justin
parent
74c1259c9a
commit
258d23bdc6
7 changed files with 417 additions and 289 deletions
|
|
@ -1,252 +1,164 @@
|
|||
# Plan
|
||||
|
||||
## Status: COMPLETE (all phases implemented + validated 2026-06-02)
|
||||
Offer healthcare regulatory filings as a **two-tier model** (internal mechanics;
|
||||
the "paper" alternative is NEVER surfaced to the client):
|
||||
|
||||
| Phase | What | Status |
|
||||
|-------|------|--------|
|
||||
| 1 | Hazmat/PHMSA handler + product (`hazmat-phmsa`, $149) | ✅ |
|
||||
| 1.5 | Order-form bundle/mutual-exclusion enforcement (server-side) | ✅ |
|
||||
| 2 | State-trucking intake form (slug-gated) + REQUIRED_FIELDS + admin-todo fields | ✅ |
|
||||
| 2.5 | BOC-3 authority-aware (active/pending/revoked/none) + upsell-approve follow-ups | ✅ |
|
||||
| 2.6 | Pipeline activation gating (`require_active` edges, FMCSA poll, waiting_on_activation) | ✅ |
|
||||
| 3 | State emissions (non-CA) product `state-emissions` ($199) | ✅ |
|
||||
| 4 | Order landing pages for all state/hazmat/emissions slugs (48 pages build) | ✅ |
|
||||
| Adv | Prerequisite-aware DOT lookup + state recommendations | ✅ |
|
||||
| 5 | Campaign builder deficiency segments + LP routing + --list-segments | ✅ |
|
||||
| Val | Consistency checker (24/24) + campaign segment test (synthetic) | ✅ |
|
||||
- **Standard service (default):** we handle the filing end-to-end. Client signs
|
||||
ONE certification and we submit + track to confirmation. (Internally this is the
|
||||
paper path — 855 to the MAC, CMS-10114 to the NPI Enumerator in Fargo — but we
|
||||
never say "paper" to the client; it's just "we file it for you.")
|
||||
- **Expedited (faster, framed positively at intake):** we ask if they can
|
||||
**electronically grant us CMS I&A Surrogate access**. We position this as
|
||||
*reducing the number of steps on our end so we can bulk-file faster* — never as
|
||||
"the alternative is paper." If yes, we file online same-day. If no, we silently
|
||||
fall back to Standard. Same price either way; surrogacy is a delegation, not
|
||||
password sharing.
|
||||
|
||||
**Remaining ops (not code):** create the 6 Listmonk source-campaign templates and
|
||||
set their `CAMPAIGN_*_ID` envs (`CAMPAIGN_FOR_HIRE_ID`, `CAMPAIGN_IRP_IFTA_ID`,
|
||||
`CAMPAIGN_INTRASTATE_ID`, `CAMPAIGN_WEIGHT_TAX_ID`, `CAMPAIGN_EMISSIONS_ID`,
|
||||
`CAMPAIGN_HAZMAT_ID`). Until set, those segments are reported by
|
||||
`--list-segments` but skipped by the scheduled run. Optional follow-up: a
|
||||
client-side incompatibility UX hint in the order form (server already enforces).
|
||||
This pass verifies the no-login paper path per service, reconciles the doc/code
|
||||
contradiction, and makes "standard = paper / expedited = surrogate" consistent
|
||||
everywhere it's surfaced.
|
||||
|
||||
## Goal
|
||||
|
||||
Make every trucker deficiency type we flag actually *fulfillable*: each flagged
|
||||
deficiency must have (1) a service handler that can complete the work, (2) a
|
||||
checkout/order path, and (3) an intake form that collects **all** information
|
||||
that handler needs before the job runs. Only after fulfillment is complete and
|
||||
verified do we extend the campaign builder to email those deficiency segments.
|
||||
Every healthcare service (federal sold + state/adjacent to add) has a verified
|
||||
**Standard (paper, no-login)** path and, where a CMS/portal exists, an
|
||||
**Expedited (surrogate/delegated)** upsell. No surface should ever present
|
||||
surrogate as *required* when a paper path exists; paper is always the default.
|
||||
|
||||
## Scope / affected areas
|
||||
- `api/src/routes/checkout.ts` (~L2155-2207) — already has the two-tier copy, BUT
|
||||
treats NPPES update/reactivation as **"online-only, surrogate required"** with
|
||||
NO standard fallback (`NPPES_ONLY_SLUGS`, `hasNppesOnly`). The directive says:
|
||||
give those a Standard paper path too (CMS-10114 to Fargo) and make surrogate the
|
||||
*expedited* option, not the only option.
|
||||
- `scripts/workers/services/npi_provider.py` — `access` strings call NPPES
|
||||
update/reactivation "NPPES via CMS I&A surrogate access (online-only)". Must
|
||||
become "Standard: CMS-10114 paper to NPI Enumerator (Fargo), client signs;
|
||||
Expedited: NPPES via I&A surrogate." Also `_STANDARD_FILING_SLUGS` currently
|
||||
excludes `nppes-update` (it has no 855) — needs a CMS-10114 paper path instead.
|
||||
- `scripts/document_gen/templates/cms855_pdf_filler.py` — working 855 paper path
|
||||
(fills 855I/B/O/A + cert-page signature anchor). **Gap:** no CMS-10114 filler
|
||||
for the NPPES standard path → likely a small new `cms10114_pdf_filler.py`.
|
||||
- `docs/healthcare-no-login-value-add.md` — already documents the CMS-10114 paper
|
||||
path; promote it to the canonical "Standard vs Expedited" matrix.
|
||||
- `site/src/pages/services/healthcare/{npi-revalidation,medicare-enrollment}.astro`
|
||||
— already describe expedited/surrogate; npi-reactivation/nppes-update order
|
||||
pages need the same two-tier framing.
|
||||
- `site/src/components/intake/steps/NpiIntakeStep.astro` + intake manifest — add
|
||||
the surrogate-access question framed positively: "Can you electronically grant
|
||||
us CMS I&A Surrogate access? It lets us bulk-file faster and cuts steps on our
|
||||
end." Optional; declining is fine and never mentions paper. The captured answer
|
||||
routes fulfillment internally (surrogate vs our Standard path).
|
||||
- `docs/state-healthcare-compliance-opportunities.md` + `new-sector-compliance-
|
||||
targets.md` — extend the two-tier classification to state/adjacent services.
|
||||
|
||||
Deficiency flags in play (live counts):
|
||||
for_hire (19,811), interstate_irp_ifta (19,761), intrastate_authority (14,081),
|
||||
state_emissions (12,424), state_weight_tax (6,289), state_permit (3,418),
|
||||
mcs150_overdue (4,539), hazmat (514), zero_fleet (134).
|
||||
|
||||
Files / systems:
|
||||
- `scripts/workers/services/__init__.py` — handler registry
|
||||
- `scripts/workers/services/state_trucking.py` — IRP/IFTA/weight-tax/permit/intrastate handler (admin-todo only today)
|
||||
- `scripts/workers/services/mcs150_update.py` — MCS-150 + reactivation (real FMCSA filing)
|
||||
- `scripts/workers/services/boc3_filing.py` — BOC-3 (Playwright)
|
||||
- **NEW** `scripts/workers/services/hazmat_phmsa.py` — only fully-missing fulfillment path
|
||||
- `site/src/lib/intake_manifest.ts` — per-service intake steps + pricing/meta
|
||||
- `site/src/components/intake/steps/DOTIntakeStep.astro` — unified DOT intake (no state-trucking sections today)
|
||||
- **NEW** `site/src/components/intake/steps/StateTruckingIntakeStep.astro` — state filing fields
|
||||
- `api/src/routes/compliance-orders.ts` — `COMPLIANCE_SERVICES` (products) + `REQUIRED_FIELDS` (validation; **none defined for any DOT/state-trucking slug today**)
|
||||
- `api/src/routes/checkout.ts` — slug allowlist
|
||||
- `api/src/routes/dot-lookup.ts` — recommended-services mapping
|
||||
- **NEW** `site/src/pages/order/*.astro` — landing pages for state-trucking + hazmat (none exist)
|
||||
- `scripts/build_trucking_campaigns.py` — campaign builder (extend last)
|
||||
|
||||
## Key findings (grounding)
|
||||
|
||||
1. **Fulfillment handlers already exist** for ~98% of flags. The single fully
|
||||
missing path is **hazmat / PHMSA registration** (no handler, product, page).
|
||||
2. **State-trucking intake collects nothing.** All 13 state slugs map to
|
||||
`["review"]` in `intake_manifest.ts` with a comment "info collected at
|
||||
checkout" — but checkout collects no per-filing fields. So IRP has no
|
||||
vehicle/weight/jurisdiction data, IFTA has no fleet/base-state, NY HUT has no
|
||||
vehicle list, intrastate-authority has no insurance/authority-type, etc. The
|
||||
handler's admin todo is therefore incomplete and an admin must chase the
|
||||
customer for data.
|
||||
3. **`REQUIRED_FIELDS` has zero entries** for any DOT or state-trucking slug, so
|
||||
the API performs no intake validation for these orders.
|
||||
4. **No dedicated order landing pages** for IRP/IFTA/state-tax/permit/intrastate
|
||||
or hazmat. Checkout works by slug, but campaign emails have no clean LP to
|
||||
drive conversions.
|
||||
5. **State emissions** flags (NY/CO/MD/NJ/MA/etc., 12,424) only map to a product
|
||||
for CA (CARB via `ca-mcp-carb`). Non-CA emissions have no product — decide
|
||||
whether to build or fold into existing state DOT/permit service.
|
||||
Out of scope this pass: building the actual surrogate Playwright automation
|
||||
(expedited fulfillment can stay human-in-PECOS for now), email-stream machinery,
|
||||
pricing changes.
|
||||
|
||||
## Approach (concrete ordered steps)
|
||||
|
||||
### Phase 1 — Close the hazmat fulfillment gap (only fully-missing path)
|
||||
1. Add `HazmatPHMSAHandler` in `scripts/workers/services/hazmat_phmsa.py`
|
||||
(admin-assisted, mirrors `state_trucking.py`: creates admin_todo with PHMSA
|
||||
registration steps, sends status email). Slug `hazmat-phmsa`.
|
||||
2. Register `"hazmat-phmsa": HazmatPHMSAHandler` in `services/__init__.py`.
|
||||
3. Add product to `COMPLIANCE_SERVICES`, meta to `intake_manifest.ts`, slug to
|
||||
checkout allowlist.
|
||||
|
||||
### Phase 1.5 — Order-form incompatibility enforcement (bundles vs components, dupes)
|
||||
Today the batch endpoint (`compliance-orders.ts` POST `/batch`) only dedupes and
|
||||
hard-codes one case (drop standalone `fcc-499a` when `fcc-499a-499q` present).
|
||||
There is no general rule preventing a customer from selecting a **bundle plus its
|
||||
own components** (e.g. `dot-full-compliance` + `mcs150-update` + `boc3-filing`, or
|
||||
`state-trucking-bundle` + `irp-registration`), or other incompatible combos. This
|
||||
double-charges and creates duplicate filings.
|
||||
|
||||
Build a single source of truth for service relationships and enforce it:
|
||||
- Add `BUNDLE_COMPONENTS` map (bundle slug -> component slugs) covering
|
||||
`dot-full-compliance`, `state-trucking-bundle`, `new-carrier-bundle`,
|
||||
`fcc-full-compliance`, plus the DB `service_bundles` rows.
|
||||
- Add `INCOMPATIBLE_PAIRS` / mutually-exclusive groups (e.g. `usdot-reactivation`
|
||||
vs `carrier-closeout`; `fcc-499a` vs `fcc-499a-499q`; emergency-temp-authority
|
||||
vs mc-authority where applicable).
|
||||
- Server-side (authoritative) in `/batch`: when a bundle is present, **drop any of
|
||||
its components** from the cart (keep the bundle), reject hard-incompatible pairs
|
||||
with a clear error, and keep dedup. Generalize the existing 499a special-case
|
||||
into this map.
|
||||
- Client-side (order form / cart UI): disable/grey out a component when its parent
|
||||
bundle is selected (and vice-versa: selecting all components suggests the bundle),
|
||||
and prevent selecting mutually-exclusive options, with an inline explanation.
|
||||
Mirror the server map so UX matches enforcement.
|
||||
|
||||
### Phase 2 — Make state-trucking intake actually collect required data
|
||||
4. Build `StateTruckingIntakeStep.astro` (one shared step, sections shown by
|
||||
slug, mirroring `DOTIntakeStep.astro`'s section-gating pattern):
|
||||
- Carrier identity: legal name, DOT#, MC#, base state, contact (prefill from DOT lookup).
|
||||
- IRP/IFTA: power units w/ VIN+plate+gross-weight rows, operating jurisdictions, fuel type.
|
||||
- Weight-distance (OR/NY/KY/NM/CT): vehicle list + gross weights + (OR) declared combined weight.
|
||||
- CA MCP+CARB: fleet engine model-years for CARB Clean Truck Check, CA# if any.
|
||||
- Intrastate authority: authority type, insurance carrier + policy#, cargo, BOC-3 on file?
|
||||
- State DOT / OSOW: as needed.
|
||||
5. Update `intake_manifest.ts`: replace `["review"]` with
|
||||
`["state-trucking", "review"]` for the 13 slugs; wire the step into the Wizard.
|
||||
6. Add `REQUIRED_FIELDS` entries in `compliance-orders.ts` for each state-trucking
|
||||
slug + the DOT slugs (mcs150, ucr, boc3, dot-registration, mc-authority, etc.)
|
||||
so intake is validated server-side. Mirror handler "Intake data needed" docstrings.
|
||||
7. Update `state_trucking.py` handler to read + surface the new intake fields in
|
||||
the admin todo (so admins get vehicle lists, jurisdictions, insurance, etc.).
|
||||
|
||||
### Phase 2.5 — Make BOC-3 authority-aware (preexisting authority handling)
|
||||
The BOC-3 attaches to a carrier's operating authority (MC/FF/MX docket). Today
|
||||
`boc3_filing.py` only reads `commonAuthorityStatus`/`contractAuthorityStatus`/
|
||||
`brokerAuthorityStatus` to print a status string and otherwise always files a
|
||||
fresh BOC-3. That can be wrong/wasteful depending on the preexisting authority.
|
||||
Add branching off the live FMCSA authority state:
|
||||
- **Active authority:** file/refresh BOC-3 only. (current behavior)
|
||||
- **Pending authority:** file BOC-3 + flag that active insurance must be on file
|
||||
for the authority to activate; create follow-up todo.
|
||||
- **Revoked/inactive authority:** file BOC-3 **and** flag/upsell reinstatement
|
||||
(OP-1 reinstatement + $80 gov fee, route via `usdot-reactivation`/`mc-authority`
|
||||
reinstatement branch). BOC-3 alone does not reinstate.
|
||||
- **No authority (USDOT only):** BOC-3 has nothing to attach to — flag that MC
|
||||
authority (`mc-authority`) is likely needed first; do not silently file.
|
||||
Implementation: have `process()/handle()` read full authority status (reuse
|
||||
`_check_boc3_status`, expanded to return structured fields), select the branch,
|
||||
adjust the admin-todo + customer email, and emit a `recommended_followups` list
|
||||
the order timeline / upsell can surface. No automatic charge for the follow-up —
|
||||
surface it for the customer/admin to approve.
|
||||
|
||||
### Phase 2.6 — Prerequisite/activation gating (wait for FMCSA "active", not just "submitted")
|
||||
There are real FMCSA dependency chains where a downstream filing must wait for an
|
||||
upstream item to be **active at the agency**, not merely submitted by us. The
|
||||
existing `pipeline_orchestrator.py` models ordering via `wait_for`, but a step is
|
||||
treated as satisfied when `pipeline_step_status == "completed"` (= our handler
|
||||
finished), which is NOT the same as FMCSA showing it active.
|
||||
|
||||
True prerequisites to enforce:
|
||||
- **MC Authority (OP-1)** requires an **active USDOT**.
|
||||
- **Authority activation** requires **BOC-3 on file + insurance (BMC-91) on file**,
|
||||
then a **mandatory ~21-day vetting/protest period** before it goes active.
|
||||
BOC-3 + insurance CAN be filed while authority is pending (parallel OK).
|
||||
- **IRP / IFTA / intrastate-authority / UCR** that depend on *active* authority
|
||||
(or active USDOT) must wait for that activation, not just for the prior order to
|
||||
be submitted.
|
||||
|
||||
Implementation:
|
||||
- Add an "activation gate" to the orchestrator: for dependency edges flagged
|
||||
`require_active: true`, poll FMCSA (mobile QC API for USDOT status; L&I for
|
||||
authority/BOC-3/insurance) and only mark the dependency satisfied when the
|
||||
agency reports active. Until then, hold the downstream step in a
|
||||
`waiting_on_activation` state with a next-poll timestamp.
|
||||
- Encode the 21-day authority vetting window as an expected-activation estimate so
|
||||
the timeline/customer comms set correct expectations.
|
||||
- Expand `PIPELINES` edges with `require_active` flags (USDOT→MC, USDOT→IRP/IFTA/
|
||||
UCR/intrastate, authority-active→IRP-for-hire/intrastate).
|
||||
- Standalone (non-bundle) orders: when a single service is ordered whose
|
||||
prerequisite isn't active yet, surface a clear "blocked until X is active"
|
||||
status + recommended prerequisite order rather than filing prematurely.
|
||||
|
||||
### Phase 3 — Decide + handle state emissions (non-CA)
|
||||
8. Either: (a) add a generic `state-emissions` service handler+product covering
|
||||
NY/CO/MD/NJ/MA clean-truck/ACT programs, or (b) map those flags to
|
||||
`state-dot-registration` / advisory-only. (Open question — see below.)
|
||||
|
||||
### Phase 4 — Order landing pages
|
||||
9. Create `site/src/pages/order/*.astro` for: irp-ifta (combined), state weight
|
||||
taxes (one templated page per state or a single state-aware page),
|
||||
ca-mcp-carb, intrastate-authority, hazmat-phmsa. Reuse existing order-page
|
||||
layout (e.g. `boc3-filing.astro`, `ucr-registration.astro` as templates).
|
||||
|
||||
### Phase 5 — Extend campaign builder (only after 1-4 verified)
|
||||
10. Add new campaign segments to `build_trucking_campaigns.py` keyed off
|
||||
`deficiency_flags`: for-hire/BOC-3+UCR, IRP/IFTA, intrastate-authority,
|
||||
state weight-tax (per-state), CA MCP/CARB, hazmat. Each links to its LP.
|
||||
11. Create the corresponding Listmonk source campaigns (templates) and wire IDs.
|
||||
1. **Confirm the CMS-10114 paper path** for NPPES data updates AND NPI
|
||||
reactivation (not just initial enumeration): paper CMS-10114 mailed to NPI
|
||||
Enumerator (PO Box 6059, Fargo ND), client signature only, no I&A login.
|
||||
Cite the official source. This is what makes NPPES services "Standard, no
|
||||
login" instead of surrogate-required. (We currently have no CMS-10114 PDF.)
|
||||
2. **Lock the two-tier matrix for the 6 federal services.** For each slug record:
|
||||
Standard path (form, mail destination, client's only action = sign / nothing),
|
||||
Expedited path (surrogate scope: PECOS and/or NPPES; what client grants),
|
||||
and whether expedited is even applicable (screening = public, no portal, so
|
||||
no expedited tier). Confirm the 855 wet-signature-cannot-be-delegated caveat
|
||||
applies to Standard; surrogate covers Expedited.
|
||||
3. **Reconcile checkout.ts.** Plan the edit so:
|
||||
- NPPES update/reactivation no longer present surrogate as *required* — remove
|
||||
the "online-only / required for those" language.
|
||||
- The surrogate ask is framed as the **faster, fewer-steps** option, never
|
||||
against a "paper" alternative. Audit/strip the existing copy that leaks
|
||||
mechanics to the client (e.g. "we'll send your CMS-855 to sign", "submit it
|
||||
to your MAC") — replace with neutral "we file it and track it for you."
|
||||
- Declining surrogate silently routes to our Standard path; no client-facing
|
||||
mention of paper/MAC/Fargo/form numbers.
|
||||
4. **Reconcile npi_provider.py.** Update `access` strings + `_STANDARD_FILING_SLUGS`
|
||||
so nppes-update/reactivation generate the CMS-10114 (or 855 reactivation)
|
||||
paper + e-sign, and the admin todo reflects Standard-default / Expedited-if-
|
||||
surrogate-granted. Mirror the existing 855 generate→upload→esign flow.
|
||||
5. **MAC + Fargo routing rule.** Document which Standard filings go where
|
||||
(855 → provider's MAC by state/jurisdiction; CMS-10114 → Fargo). Confirm
|
||||
`practice_state` intake field drives MAC envelope addressing.
|
||||
7. **Daily batched-mail fulfillment (Standard path).** Design the operational
|
||||
flow for paper filings that are signed + pending submission:
|
||||
- On each **postal working day morning** (skip weekends + federal/USPS
|
||||
holidays), gather ALL signed-and-pending paper filings, **group by
|
||||
destination agency/address** (each MAC, the NPI Enumerator in Fargo, each
|
||||
state Medicaid/CLIA agency).
|
||||
- For each destination, **merge all that day's documents into one print job**
|
||||
plus a **cover sheet** (Performance West sender, destination agency, date,
|
||||
enclosed-count, per-item list of order# / provider / NPI / form). One
|
||||
**Priority Mail envelope per agency** → saves postage + handling.
|
||||
- Mark each included order as "mailed" with the batch date + tracking #.
|
||||
- Build this as a worker (a `daily_paper_batch` job + a cover-sheet generator
|
||||
in document_gen), mirroring existing worker/cron patterns
|
||||
(`infra/cron/*`, `business_days.py` for the working-day calendar). Decide:
|
||||
fully-automated print-to-PDF batch that a human prints + drops, vs.
|
||||
print-API (Lob/Click2Mail) auto-mail. **Recommend phase 1 = generate the
|
||||
per-agency batched PDF + cover sheet + manifest for a human to print & mail;
|
||||
phase 2 = wire a print-mail API.**
|
||||
8. **Extend two-tier to state/adjacent services.** For each (State Medicaid
|
||||
enroll/reval, CAQH re-attest, payer credentialing, DEA renewal, state CSR,
|
||||
PDMP, CLIA, license renewal+CME) classify:
|
||||
- **Standard (no-login):** paper/mail-in form + one client signature?
|
||||
(e.g. CLIA = CMS-116 paper to state; Medicaid varies — some paper.) These
|
||||
feed the same daily batched-mail flow, grouped by their state agency.
|
||||
- **Expedited (delegated):** the lightest legitimate delegation that avoids a
|
||||
client *login* — e.g. CAQH "authorized administrator/org" grant, Medicaid
|
||||
"delegated official" on the app, payer EDI/CAQH attestation rights, an LOA.
|
||||
Distinguish "client signs one authorization once" (acceptable, still
|
||||
no-login) from "client must log in / share credentials" (never).
|
||||
- Flag services that are genuinely portal-only with NO paper standard so
|
||||
marketing never claims "no logins" for them.
|
||||
9. **Sequence the rollout** by (Standard-feasibility first) × revenue, and write
|
||||
the two doc updates + the small code edits (checkout.ts, npi_provider.py,
|
||||
optional cms10114_pdf_filler.py, and the daily batch worker + cover sheet).
|
||||
All gated on approval.
|
||||
|
||||
## Validation (how each part is verified)
|
||||
|
||||
- **Handlers:** unit-invoke each handler with a synthetic `order_data` dict in a
|
||||
throwaway script; assert an `admin_todos` row is created with the expected
|
||||
fields and (dev mode) no live filing fires. Confirm `SERVICE_HANDLERS` resolves
|
||||
every new slug.
|
||||
- **Intake completeness (the core ask):** write a check that, for every slug,
|
||||
cross-references `REQUIRED_FIELDS[slug]` against the fields the intake step
|
||||
emits and against the keys the handler reads — fail if a handler-needed field
|
||||
is never collected. This is the verifiable "we collect all needed info" metric.
|
||||
- **Checkout/products:** assert every flagged slug exists in `COMPLIANCE_SERVICES`,
|
||||
`SERVICE_META`, checkout allowlist, and `SERVICE_HANDLERS` (one consistency test).
|
||||
- **Order pages:** build site (`astro build` / existing build script) and confirm
|
||||
each new `/order/<slug>` route renders; smoke-load locally.
|
||||
- **Campaign builder:** run `build_trucking_campaigns.py --dry-run` and assert
|
||||
each new segment selects a nonzero, deduped audience pointing at a valid LP.
|
||||
- **End-to-end:** place a test order per new slug through checkout in dev, verify
|
||||
intake validation blocks missing fields, and the handler produces a complete
|
||||
admin todo.
|
||||
- **Source-grounded:** every Standard (paper) and Expedited (delegation) claim
|
||||
cites the official instruction (CMS-855 instr, CMS-10114 instr, CMS-116 for
|
||||
CLIA, state Medicaid enrollment page, CAQH/payer docs). No unsourced claim.
|
||||
- **Consistency sweep:** after edits, `grep` for "online-only" / "required" /
|
||||
"surrogate" / "no login" across checkout.ts, npi_provider.py, and the service
|
||||
pages — confirm none present surrogate as *required* where a paper path exists,
|
||||
and Standard is the default on every surface.
|
||||
- **Standard path mechanism check:** `cms855_pdf_filler.fill_cms855("855i",...)`
|
||||
still yields filled PDF + cert anchor (read-only smoke render). If CMS-10114
|
||||
filler is built, same smoke render proves a signable Fargo-bound PDF.
|
||||
- **Expedited path check:** confirm the surrogate-grant CTA + `ia_surrogacy`
|
||||
success action + admin todo together let a human file in PECOS/NPPES same-day;
|
||||
surrogate scope wording matches what CMS I&A actually grants (PECOS vs NPPES).
|
||||
- **Matrix completeness:** every service (federal + state) has Standard + (where
|
||||
applicable) Expedited rows with a definite client-action column and source;
|
||||
no "unknown" and no service that's portal-only-but-marketed-as-no-login.
|
||||
|
||||
## Open questions / decisions
|
||||
|
||||
**RESOLVED (per user 2026-06-02):**
|
||||
1. **BOC-3 follow-ups + prerequisite blockers → upsell-approve, advise pre-order
|
||||
where possible.** Two layers:
|
||||
- *Pre-order advisory (preferred):* extend the existing DOT Compliance Check
|
||||
tool (`site/public/tools/dot-compliance-check/`) + `dot-lookup` recommended
|
||||
services to be **prerequisite-aware**. When a recommended service needs an
|
||||
active prerequisite (e.g. IRP needs active authority), show the dependency,
|
||||
pre-select the prerequisite, order the cart correctly, and state the ~21-day
|
||||
authority activation expectation — all before payment.
|
||||
- *Post-order upsell-approve:* when a handler discovers a blocker mid-fulfillment
|
||||
(e.g. BOC-3 ordered but authority revoked → needs reinstatement), write a
|
||||
`recommended_followups` entry on the order and render a one-click, pre-filled
|
||||
"Add this service" card on the order timeline/portal. Customer confirms + pays
|
||||
via the existing checkout. **No auto-charge.**
|
||||
- *Standalone checkout guard:* if a service is bought directly and its prereq
|
||||
isn't active at FMCSA, warn + offer to add the prereq rather than filing
|
||||
something unfulfillable.
|
||||
2. **State emissions (non-CA): build a real product.** Add a `state-emissions`
|
||||
service (handler + product + intake + page) covering NY/CO/MD/NJ/MA clean-truck
|
||||
/ Advanced Clean Trucks programs (CA stays on `ca-mcp-carb`).
|
||||
3. **Pre-order advisory: yes.** Covered by 1 above — reuse the compliance-check
|
||||
tool as the advisory surface.
|
||||
|
||||
**STILL OPEN:**
|
||||
4. Pricing for `hazmat-phmsa` and `state-emissions`.
|
||||
**DEFAULT:** `hazmat-phmsa` = $149 (admin-assisted PHMSA registration; gov fee
|
||||
$25 placardable-hazmat reg billed at cost). `state-emissions` = $199
|
||||
(NY/CO/MD/NJ/MA clean-truck / ACT advisory + registration assist).
|
||||
5. Vehicle-list intake fidelity.
|
||||
**DEFAULT:** lightweight up front — collect fleet count + base/operating states
|
||||
+ fuel type + gross-weight bracket at intake; collect full per-vehicle
|
||||
VIN/plate/weight rows via a post-order follow-up form only when the specific
|
||||
filing requires it (IRP, weight-distance taxes). Keeps conversion high.
|
||||
6. Standalone-order prereq guard.
|
||||
**DEFAULT:** warn + offer to add the prerequisite (pre-selected), allow override
|
||||
("file anyway"). Never a hard block.
|
||||
7. Long-term home for the reviewable plan (`docs/plans/` used here; no
|
||||
`side_panel` tool in this harness).
|
||||
1. **NPPES update/reactivation Standard path:** is CMS-10114 paper-to-Fargo
|
||||
accepted for *changes/reactivation* today (RESOLVE in step 1)? If yes, both
|
||||
become Standard-default + surrogate-expedited. If CMS has gone online-only,
|
||||
they stay surrogate-required and we say so honestly. (Directive assumes paper
|
||||
works as Standard; step 1 verifies.)
|
||||
2. **Build `cms10114_pdf_filler.py` this pass?** Needed for a real NPPES Standard
|
||||
path. Recommend: yes if step 1 confirms paper, mirroring the 855 filler;
|
||||
otherwise defer.
|
||||
3. **State Medicaid scope:** classify the mechanism generically + verify top ~5
|
||||
states by our lead density now; template the rest. (50-state research is a
|
||||
separate effort.)
|
||||
4. **CAQH / payer credentialing tier:** almost certainly Expedited = "client
|
||||
signs one authorization, no login" (category C). Confirm we market that as
|
||||
"no logins for you" with precise wording.
|
||||
5. **Expedited pricing/positioning:** RESOLVED — expedited is **not** a paid
|
||||
tier and we never expose "paper" as the alternative. It's an intake question
|
||||
framed positively ("electronically granting surrogate access lets us bulk-file
|
||||
faster / fewer steps on our end"). If yes → online; if no → silent Standard
|
||||
fallback. Same price. No price delta, no separate product, no mention of paper.
|
||||
6. **Client-facing messaging rule:** never surface mechanics to the client —
|
||||
no "paper", "CMS-855", "CMS-10114", "MAC", or "Fargo" in any client copy
|
||||
(cold email, order page, checkout, intake). The only client-visible choice is
|
||||
the positive surrogate question; everything else is "we file it for you." This
|
||||
applies to the checkout copy audit in step 3.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue