# Offer & Onboarding — Requirements Matrix

**Status:** Draft spec for the planned offer/onboarding document-collection agent.
**Ground truth:** `~/Downloads/Hire Requirements vF.docx.md` (Treetop "Hire Requirements by State" SOP, Feb 2026). This file is a faithful, structured restatement of that SOP plus the universal federal/payroll items it references — it is the source the agent should resolve requirements against. Where the SOP is ambiguous, it is flagged in §7.

---

## 0. Scope & per-tenant flexibility

**This matrix is the *initial default for Treetop*, not a global spec.** It is seeded as one versioned configuration — `policy_version: treetop-hire-requirements-v1` — owned by the Treetop organization. The system is **per-tenant and config-driven**: every organization gets its own requirements config, and onboarding a second customer (e.g. Bright Achievements) means authoring *their* config, not editing this one. Treetop is simply where we start because it's the most demanding case.

What is **flexible per tenant** (nothing below is hardcoded):

- **The requirement set itself.** Which credential policies, gates, role types, and axes are enabled is per-org. Not every company hires ABA technicians, uses the RBT/40-hour pathway, or has Tricare/Medicaid payer logic. A simpler tenant may enable only the universal bundle (offer letter, payroll, education, training) and a couple of credentials.
- **The axes of variation.** The five-axis resolution model (§1) is the *maximum* shape. The resolver **degrades gracefully** when an axis is absent: a tenant with no payer logic, no named clinics, or no clinic-vs-home distinction resolves on the remaining axes (e.g. state × role only). An axis with no rules contributes nothing.
- **Integration / storage target.** Where collected documents and extracted fields are written is a **per-tenant choice**, not a constant — see §9. Treetop writes credentials to its **Lumary** Certifications object; Bright Achievements uses **Rippling**; another tenant might use **Salesforce** or keep documents only inside Maigrate. This is selected via the org's `Integration` rows and resolved through an adapter.
- **Editable knobs.** Within a tenant's config, admins can flip a credential required↔optional, change expiry handling, and adjust name-match strictness without code changes (mirrors the Document Review settings surface).

**Design implication:** the config is **static, versioned, admin-owned data** (per org), and the resolver/agent consume it as context. Treat this document as the *content* of one such config (Treetop's), and the §3–§7 tables as the seed values — not as the universal rule set.

---

## 1. Resolution model — how a hire's required-doc set is computed

The required document set is **not** a flat list. It is resolved from five inputs:

```
required_docs, gates  =  resolve(state, role_type, payer/plan, location/clinic, setting)
```

| Axis | Values | What it controls |
|---|---|---|
| **State** | AZ, CO, GA, NC, NM, NV, OK, TX, UT, VA (10 markets) | Role mix + state-mandated checks (NC→DHSR, NV→rostering, UT→TB+fingerprint, NM→NPI-for-BT) |
| **Role type** | Tricare RBT, RBT, (ABAT*), 40-Hour Certificate, BT | Selects the base requirement column (§3) |
| **Payer / plan** | Tricare, Medicaid (+ state MCO), BCBS, UHC, Aetna, Champ VA | Drives *which role* is hired, and some fields (BCBS MCO → Supervisor Name in NM; "Credential with Payor") |
| **Location / clinic** | Named clinics/cities (SP & Raeford NC; Savannah/Columbus/Hinesville GA; Colorado Springs; Arlington/Norfolk VA) | Forces a role (e.g. Tricare RBT) at specific sites |
| **Setting** | Clinic-based vs. in-home | Clinic-based adds TB + fingerprinting + per-clinic CPR (orthogonal to state) |

\* **ABAT** (QABA-board) is named in the SOP preamble as an alternative to RBT but has no requirements table — model it as a variant of the RBT pathway, not a separate role (see §7).

> "There are exceptions to every rule… The guidance below represents where we want teams to focus their recruiting efforts, not an absolute prohibition on other role types." — so the per-state role mix is a **default**, not a hard constraint. The agent should treat (state→role) as a recommended default that an operator can override per hire.

---

## 2. Gates (map onto pipeline stages)

The SOP defines two hard checkpoints. These become stage boundaries the agent enforces:

| Gate | Blocks until satisfied | Items that gate it |
|---|---|---|
| **Cannot move to training** | Candidate can't begin training | Proof of Education; Viventium payroll sign-up (incl. I-9, W-4, ID, direct deposit, handbook) |
| **Cannot move to scheduling** | Candidate can't be scheduled on a client | Proof of Completing Training (all 6 modules); + state add-ons: UT TB+fingerprint, NV Medicaid credentialing + rostering, OK payor credentialing |
| **Before providing services (TX only)** | Unique to Texas | Tricare RBT credentialing must be complete *before* work |
| **Before starting with a client (NM)** | NM 40-hr pathway | 40-Hour cert (3rd ed.) before start; RBT within 30 days of start |

Note today's code models only a single `before_interview` document stage — this needs at least **training-gate** and **scheduling-gate** stages added.

---

## 3. Role × Requirement matrix (consolidated from the 4 SOP role tables)

Cell = `✓` (always required for that role) · a **condition** (state/location/payer that triggers it) · blank (not required).

| Requirement | Tricare RBT | RBT | 40-Hour Cert | BT |
|---|---|---|---|---|
| **Signed offer letter** | ✓ | ✓ | ✓ | ✓ |
| **Formal application** | ✓ | ✓ | ✓ | ✓ |
| **Payroll sign-up (Viventium)** ⟶ §4 | ✓ | ✓ | ✓ | ✓ |
| **HS Diploma / Education** ⟶ §4 | ✓ | ✓ | ✓ | ✓ |
| **Proof of Completing Training** ⟶ §4 | ✓ | ✓ | ✓ | ✓ |
| **Additional Certs → Lumary** | As needed | As needed | As needed | As needed |
| **NPI Number** | ✓ | ✓ | ✓ | **NM only** |
| **Basic Background Check** | — (uses Tricare bg) | ✓ | ✓ | ✓ |
| **Tricare Background Check** | ✓ | **NC RBTs** | — | — |
| **CPR (In-Person)** | ✓ | — | — | **1 person per AZ clinic** |
| **CPR Expiration Date** | ✓ | — | — | **AZ clinics** |
| **RBT Certificate (BACB)** | ✓ | ✓ | — | — |
| **Cert Issue Date** | RBT | RBT | 40-Hour | — |
| **Cert Expiration Date** | RBT | RBT | 40-Hour | — |
| **40-Hour Certificate** (+9 validity fields ⟶ §4) | — | — | ✓ | — |
| **Supervisor Name** | ✓ | ✓ | ✓ | **NM** |
| **Credential with Payor** ⟶ §5 | ✓ | NV (Medicaid), OK, NM (Medicaid) | NM, OK, GA, UT, NC | NM (Medicaid) |
| **TB Test (+ Expiration)** | Utah, AZ clinic | Utah, AZ clinic | — | AZ clinics |
| **Fingerprinting** | Utah, AZ clinic | Utah, AZ clinic | — | AZ clinics |
| **DHSR Check** | NC | NC | NC | NC |
| **State Rostering** | NV | NV | — | — |

---

## 4. Universal / bundle sub-requirements (all roles, all states)

### 4a. Payroll Sign-up (Viventium) — *gates training* — **this is the "other forms" set**
- **Government-Issued ID** (copy of ID)
- **Work Authorization (I-9)**
- **Tax Forms (W-4 or state equivalent)**
- **Direct Deposit Authorization** (payment info)
- **Signed Employee Handbook**

### 4b. Proof of Education — *gates training* — acceptable forms:
- HS Diploma **& Official HS Transcript** → fields: graduate full name, school name, graduation date
- College/University Diploma **or** Official Transcript → fields: graduate full name, institution name, degree conferred, proof of completed education, college graduation date

### 4c. Proof of Completing Training — *gates scheduling* — all 6 required:
HIPAA · Fraud, Waste & Abuse · Cultural Competency · Mandated Reporter · Blood Borne Pathogens · Role-Specific Training (per Training dept)

### 4d. 40-Hour Certificate validity — all 9 must be present (verified by Recruiting):
Full Legal Name · Training Start & End Date (or "completed on X") · Total Time Completed · Responsible Trainer's Name · Trainer's BACB Cert # (BCBA/BCaBA/BCBA-D) · Trainer's Signature **or** Company Branding · proof training ≥40 hrs (hours+minutes) · proof completed within 180 days & not fewer than 5 days · proof trainer was BCBA/BCaBA/BCBA-D (with required supervision training)

### 4e. Tricare RBT Credentialing packet — collected by **Credentialing team**, separate from onboarding:
Name · Date of Birth · Social Security Number · RBT Certificate (BACB) · RBT Expiration Date · Supervisor Name · CPR (In-Person, Tricare-approved list) · Tricare Background Check
- Timing: Tricare credentialing **does not** need to be complete at hire (begin during onboarding) — **except Texas: required before work.**

---

## 5. Payer / credential-with-payor detail

"Credential with Payor" = enroll the employee with a specific payor so their services are billable; begins once background check is complete; varies by state + payor.

| State | Role | Payor credentialing detail |
|---|---|---|
| AZ | RBT | RBT hired **only** for BCBS, UHC, Champ VA, Aetna cases. Tricare not taken in AZ yet. |
| NV | RBT | Medicaid — portal login + **wet signature**; + state rostering before scheduling |
| OK | RBT | Payor credentialing (generic) before scheduling |
| NM | all roles | Medicaid — portal login + application signature; **Supervisor Name required for BCBS MCO**; NPI required |
| NC | Medicaid roles | **DHSR check**; NC RBTs also need Tricare background check |
| GA, UT | 40-Hour | Credential-with-payor applies to the 40-hr pathway |

---

## 6. Ongoing / recurring (must be maintained; "ownership & cadence TBC")
- **Monthly:** OIG / LEIE / SAM re-check
- **Every 120 days:** CAQH re-attestation
- **Annual:** training renewals (Cultural Awareness, HIPAA, FWA, + Mandated Reporting, Bloodborne Pathogens); COI renewal upload
- **Ongoing:** ≥1 person per clinic maintains current CPR
- **Expiration-tracked fields:** CPR Exp · RBT Cert Exp · 40-Hour Cert Exp · TB Test Exp

---

## 7. Per-state overlay

| State | Primary role | As-needed | Payer driver | Location conditions | State checks | Timing |
|---|---|---|---|---|---|---|
| **Arizona** | BT (statewide) | RBT (BCBS/UHC/Champ VA/Aetna); 40-hr & Tricare not required | BCBS, UHC, Champ VA, Aetna; Tricare N/A | Clinic techs: TB + fingerprint + per-clinic CPR | TB, fingerprint (clinics) | — |
| **Colorado** | RBT | Tricare RBT | Tricare | Colorado Springs: all Tricare-credentialed | — | — |
| **Georgia** | RBT | Tricare RBT (named cities); 40-hr/BT only to train→RBT | Tricare | Tricare RBT: Savannah, Columbus, Hinesville | — | 40-hr/BT must certify to RBT before active w/ client |
| **North Carolina** | Mixed | Tricare RBT (SP & Raeford); RBT case-by-case (all get Tricare bg); 40-hr rest | NC Medicaid; Tricare | Tricare RBT: SP Clinic, Raeford Clinic | DHSR (Medicaid roles); Tricare bg for NC RBTs | — |
| **New Mexico** | BT / RBT / 40-hr | Tricare RBT | BCBS MCO; Medicaid | — | NPI (all incl. BT); Medicaid credentialing; Supervisor Name (BCBS MCO) | 40-hr before start; RBT within 30 days (co. policy; state = 6 mo) |
| **Nevada** | RBT | Tricare RBT | Medicaid | — | Medicaid credentialing (portal + wet sig); state rostering | gate before scheduling |
| **Oklahoma** | RBT | Tricare RBT | Payor (generic); Tricare | — | Payor credentialing before scheduling; no 40-hr/BT | gate before scheduling |
| **Texas** | RBT | Tricare RBT | Tricare | — | Tricare cert before services (unique); no 40-hr/BT | before providing services |
| **Utah** | RBT | Tricare RBT; 40-hr exceptions only | Tricare | — | TB + fingerprint for ALL RBTs | before scheduling |
| **Virginia** | RBT (case-by-case) + BT (rest) | Tricare RBT | Tricare | BT outside Arlington & Norfolk | — | — |

---

## 8. Open decisions / human-input flags
1. **ABAT/QABA** — model as RBT variant or own role? (no requirements table in SOP)
2. **NM RBT timing** — enforce company 30-day or state 6-month rule?
3. **Recurring checks** — "ownership and cadence to be confirmed" (OIG monthly, CAQH 120-day, annual renewals)
4. **"Credential with Payor" generality** — OK says generic "payor"; NV/NM specify Medicaid. Resolve generic vs. payer-specific.
5. **Clinic entity** — "1 person per AZ clinic must hold CPR" is a per-clinic rule, not per-person — the data model needs a clinic concept, not just person-level fields.
6. **Per-tenant storage** — Treetop = Lumary Certifications object; Bright Achievements = Rippling. Storage target must be an adapter, not hardcoded.
7. **Background-check gating** (from `application_requirements.md` open Qs) — gate the offer, or collect post-acceptance?
8. **Champ VA** — appears as an AZ RBT payer with no requirement column; confirm it folds into the generic RBT set.

---

## 9. Integration & storage adapters (per-tenant)

Once a document is collected and validated, *where it lands* is a **per-tenant integration choice**, resolved through an adapter — never hardcoded. The org's enabled `Integration` rows determine the target; if none is configured, documents live only inside Maigrate.

| Tenant (example) | Storage target | Notes |
|---|---|---|
| **Treetop** | **Lumary** — Certifications object on the technician contact | Two-step: create certification record (required field = certification *type*), then attach the file. Fields: cert number, issue/expiration dates, state, certifying board, supervisor name. |
| **Bright Achievements** | **Rippling** | Offers + onboarding paperwork live in Rippling; credential mapping TBD. |
| (generic) | **Salesforce** contact, or **Maigrate-only** | Fallback when the tenant has no dedicated credentialing system. |

**Adapter contract** (one implementation per provider, following the existing `app/Integrations/<Service>/` pattern with a `Contracts/` interface + `Fake` for tests):

- `writeCredential(case, documentType, extractedFields, fileRef)` → external record id
- `readCredentialStatus(case, documentType)` → external status (for reconciliation)

The resolver/agent is **storage-agnostic**: it computes the required set and tracks collection in Maigrate; the adapter is invoked only to mirror an accepted document into the tenant's system of record. Selecting/adding a provider for a tenant is a config + `Integration` row, not a code change in the onboarding module.