Clarity Engine — Program Router Skill

Version: 1.0 | Status: Implementation-Ready — Gear 1

Clarity Engine — Program Router Skill

Version: 1.0 | Status: Implementation-Ready — Gear 1

Scope: Receives a validated BorrowerProfile object from the Borrower Profile Skill and produces a ProgramEvaluationQueue — an ordered list of eligible mortgage programs for the downstream family skills to evaluate. The Router determines WHICH programs run and in WHAT order. It does not underwrite. It does not compute final rates, PMI factors, or qualifying DTI. It gates, sequences, and hands off.

Confidential: PreFi, Inc. / Purpose Technology, Inc. d/b/a Purlend

SKILL PURPOSE

The Program Router is the decision switchboard between intake (Borrower Profile Skill) and evaluation (family skills: VA Module, Conventional, FHA, DSCR). Its output is the ProgramEvaluationQueue — a structured, ordered list telling downstream skills exactly which programs to run, which to skip, and why.

This skill produces:

1. An eligibility determination for each program: ELIGIBLE | INELIGIBLE | CONDITIONAL
2. A priority-ordered evaluation queue (Priority 1 = evaluate first)
3. A preliminary cost comparison across eligible programs (payment and cash-to-close estimates)
4. Preliminary MI/funding fee calculations for each eligible program
5. A no_viable_programs flag with an action plan if no standard program qualifies

This skill does NOT produce:

• A final qualifying DTI (computed per program in family skills)
• A final rate (locked in Scenario Generation Skill)
• A loan approval or denial
• A full residual income test (computed in VA Module Skill)

INVOCATION

Invoke this skill when:

• handoff_ready = true is emitted by the Borrower Profile Skill
• A borrower's profile has been updated and re-routed is needed
• A downstream family skill reports a blocking eligibility gap and asks for re-routing

Trigger phrases:

• "Route this profile to the right programs"
• "Which loan programs does this borrower qualify for?"
• "What programs should we run?"
• "Profile handoff complete — route now"

Required input: Complete BorrowerProfile object with handoff_ready = true. If handoff_ready = false, return immediately with: ROUTER_BLOCKED — BorrowerProfile not complete. Resolve blocking fields first.

EXECUTION SEQUENCE

Stage 1 — Validate handoff_ready
Stage 2 — Extract routing inputs from BorrowerProfile
Stage 3 — Apply Gate 1: Occupancy hard gates
Stage 4 — Apply Gate 2: Loan amount / conforming limit
Stage 5 — Apply Gate 3: Credit score eligibility per program
Stage 6 — Apply Gate 4: LTV / down payment eligibility per program
Stage 7 — Apply Gate 5: DSCR preliminary check (investment properties only)
Stage 8 — Compute preliminary MI and funding fee per eligible program
Stage 9 — Compute preliminary cost comparison (payment and CTC per program)
Stage 10 — Assign priority order
Stage 11 — Build and emit ProgramEvaluationQueue

Apply all gates in sequence. A program eliminated at any gate does not re-enter. A program that survives all gates is ELIGIBLE. A program that survives with caveats is CONDITIONAL.

PROGRAM REFERENCE TABLE

These are the four standard programs the Router evaluates. All thresholds are fixed guidelines — actual lender overlays may be stricter. Flag LENDER_OVERLAY_RISK when borrower is near a boundary.

Conforming loan limit 2026: $806,500 (baseline CONUS). High-cost area limits differ — flag HIGH_COST_AREA_CHECK if property is in CA, NY, HI, AK, DC, or other known high-cost markets.

STAGE 1 — VALIDATE HANDOFF

IF BorrowerProfile.handoff_ready ≠ true:
  STOP. Return:
    status: ROUTER_BLOCKED
    reason: "BorrowerProfile not complete. handoff_ready = false."
    action: "Resolve all blocking_missing_fields before routing."

IF BorrowerProfile.validation.income_split_error = true:
  STOP. Return:
    status: ROUTER_BLOCKED
    reason: "INCOME_SPLIT_ERROR detected. gmi_for_dti = net_income_for_va_residual."
    action: "Rebuild income stage in Borrower Profile Skill before routing."

STAGE 2 — EXTRACT ROUTING INPUTS

Pull these fields from the BorrowerProfile object. These are the only inputs the Router uses. If any are absent despite handoff_ready = true, flag ROUTER_DATA_ERROR and list the missing fields.

FROM borrower:
  veteran_flag                  boolean
  disability_flag               boolean
  va_use_count                  integer — 0 = first use, 1+ = subsequent use (default 0 if unknown)
  first_time_homebuyer_flag     boolean
  qualifying_credit_score       integer  (lower of two middle scores if co-borrower)
  credit_tier                   integer 1–8
  self_employed_flag            boolean

FROM deal:
  deal_type                     PURCHASE | RATE_REFI | CASH_OUT_REFI | DEBT_CONSOLIDATION_REFI | TERM_REFI
  requested_loan_amount         decimal
  down_payment_amount           decimal  (0.00 for refis)
  purchase_price                decimal  (PURCHASE) or estimated_value (REFI)
  estimated_closing_costs       decimal
  seller_concession_amount      decimal
  desired_cash_out_amount       decimal  (CASH_OUT_REFI only)

FROM property:
  occupancy_type                PRIMARY | SECOND_HOME | INVESTMENT
  property_type                 SFR | CONDO | TOWNHOME | 2_UNIT | 3_UNIT | 4_UNIT | PUD | MANUFACTURED
  unit_count                    integer 1–4
  monthly_tax                   decimal
  monthly_insurance             decimal
  hoa_monthly                   decimal
  gross_rent_monthly            decimal  (INVESTMENT only — may be null)
  state                         string   (for high-cost area check)

FROM preliminary_signals:
  ltv_estimate                  decimal
  funds_available_for_closing   decimal
  cash_to_close_estimate        decimal
  preliminary_dti_signal        CLEAR | WATCH | ELEVATED | CONCERN
  approval_readiness_score      decimal

FROM routing:
  routing_flags                 list — all flags set by Borrower Profile Skill

Derived inputs (computed in Stage 2):

property_value = purchase_price  (PURCHASE)  OR  estimated_value  (REFI)
base_loan_amount = requested_loan_amount  (as computed by Borrower Profile Skill)
ltv = ltv_estimate  (as computed by Borrower Profile Skill)
down_payment_pct = down_payment_amount / property_value  (floor 0.00)

STAGE 3 — GATE 1: OCCUPANCY HARD GATES

These gates are absolute. No compensating factors override them.

occupancy_type = PRIMARY:
  VA:           pass_gate_1 = true   (subject to veteran_flag in Gate 3)
  FHA:          pass_gate_1 = true
  CONVENTIONAL: pass_gate_1 = true
  DSCR:         pass_gate_1 = false  → INELIGIBLE, reason = "DSCR requires INVESTMENT occupancy"

occupancy_type = SECOND_HOME:
  VA:           pass_gate_1 = false  → INELIGIBLE, reason = "VA requires PRIMARY occupancy"
  FHA:          pass_gate_1 = false  → INELIGIBLE, reason = "FHA requires PRIMARY occupancy"
  CONVENTIONAL: pass_gate_1 = true   (additional constraints applied in Gate 4)
  DSCR:         pass_gate_1 = false  → INELIGIBLE, reason = "DSCR requires INVESTMENT occupancy"

occupancy_type = INVESTMENT:
  VA:           pass_gate_1 = false  → INELIGIBLE, reason = "VA requires PRIMARY occupancy"
  FHA:          pass_gate_1 = false  → INELIGIBLE, reason = "FHA requires PRIMARY occupancy"
  CONVENTIONAL: pass_gate_1 = true   (investment overlays applied in Gate 4)
  DSCR:         pass_gate_1 = true   (subject to remaining gates)

STAGE 4 — GATE 2: LOAN AMOUNT vs CONFORMING LIMIT

conforming_limit = 806500  (2026 baseline — override if high_cost_area_flag = true)

IF state IN [CA, NY, HI, AK, DC, MA, CO, WA, NJ, CT, VA, MD]:
  flag HIGH_COST_AREA_CHECK
  note: "Conforming limit may be higher. Verify county-level limit before eliminating programs."

FOR each program that passed Gate 1:

  VA:
    No conforming limit since Blue Water Navy Act 2020 (full entitlement required for no down payment)
    pass_gate_2 = true  (for all loan amounts with full entitlement)
    IF base_loan_amount > 806500 AND va_use_count > 0:
      flag VA_REMAINING_ENTITLEMENT_CHECK
      note: "Prior VA loan use may require down payment on amounts above county limit. Verify entitlement."

  FHA:
    IF base_loan_amount > conforming_limit:
      pass_gate_2 = false  → INELIGIBLE, reason = "FHA standard limit exceeded ($806,500). High-balance FHA may apply."
      flag ROUTE_JUMBO_FHA
    ELSE:
      pass_gate_2 = true

  CONVENTIONAL:
    IF base_loan_amount > conforming_limit:
      pass_gate_2 = false  → INELIGIBLE, reason = "Conventional conforming limit exceeded ($806,500)."
      flag ROUTE_JUMBO
    ELSE:
      pass_gate_2 = true

  DSCR:
    DSCR has no standard conforming limit — lender-specific
    pass_gate_2 = true
    IF base_loan_amount > 2000000:
      flag DSCR_LARGE_BALANCE_ADVISOR_REVIEW

STAGE 5 — GATE 3: CREDIT SCORE ELIGIBILITY

Use qualifying_credit_score for all program eligibility checks — not the primary borrower's individual score.

FOR each program that passed Gate 2:

  VA:
    IF qualifying_credit_score ≥ 580:
      pass_gate_3 = true
    ELIF qualifying_credit_score ≥ 500:
      pass_gate_3 = CONDITIONAL
      conditional_note = "Score 500–579 below standard VA lender overlay. Requires lender with 580 floor exception."
      flag LENDER_OVERLAY_RISK
    ELSE:  (score < 500)
      pass_gate_3 = false  → INELIGIBLE, reason = "Score below VA lender minimum (500)"

  FHA:
    IF qualifying_credit_score ≥ 580:
      pass_gate_3 = true
      fha_down_payment_tier = "3.5%"  (3.5% down available)
    ELIF qualifying_credit_score ≥ 500:
      pass_gate_3 = true
      fha_down_payment_tier = "10%"  (10% down required)
      flag FHA_10PCT_DOWN_REQUIRED
    ELSE:  (score < 500)
      pass_gate_3 = false  → INELIGIBLE, reason = "FHA minimum credit score is 500"

  CONVENTIONAL:
    IF qualifying_credit_score ≥ 620:
      pass_gate_3 = true
    ELSE:
      pass_gate_3 = false  → INELIGIBLE, reason = "Conventional minimum credit score is 620"

  DSCR:
    IF qualifying_credit_score ≥ 640:
      pass_gate_3 = true
    ELIF qualifying_credit_score ≥ 620:
      pass_gate_3 = CONDITIONAL
      conditional_note = "Score 620–639 below DSCR standard. Some lenders require 640+. Overlay risk."
      flag LENDER_OVERLAY_RISK
    ELSE:
      pass_gate_3 = false  → INELIGIBLE, reason = "DSCR standard minimum is 640"

Additional VA flag in Gate 3:

IF program = VA:
  IF veteran_flag ≠ true:
    pass_gate_3 = false  → INELIGIBLE, reason = "VA requires veteran status"
  IF disability_flag = true:
    va_funding_fee_exempt = true
  ELSE:
    va_funding_fee_exempt = false

STAGE 6 — GATE 4: LTV / DOWN PAYMENT ELIGIBILITY

Compute down_payment_required and required_cash_to_close per eligible program. Flag if funds_available_for_closing < required_cash_to_close.

Down Payment Required Per Program

VA:

down_payment_required = 0.00
va_base_loan = base_loan_amount  (purchase_price - 0)
ltv_before_fee = va_base_loan / property_value
pass_gate_4 = true  (VA has no LTV cap with full entitlement)

FHA:

IF fha_down_payment_tier = "3.5%":
  down_payment_required = property_value × 0.035
  fha_base_loan = property_value - down_payment_required
  fha_ltv = fha_base_loan / property_value
  IF fha_ltv > 0.965:  (rounding edge case)
    down_payment_required = property_value - (property_value × 0.965)
    fha_base_loan = property_value × 0.965

IF fha_down_payment_tier = "10%":
  down_payment_required = property_value × 0.10
  fha_base_loan = property_value - down_payment_required
  fha_ltv = fha_base_loan / property_value  (= 0.90)

IF fha_base_loan > conforming_limit:
  pass_gate_4 = false → INELIGIBLE (conforming limit exceeded post down-payment)
ELSE:
  pass_gate_4 = true

CONVENTIONAL:

IF occupancy_type = PRIMARY:
  down_payment_min_pct = 0.03
  down_payment_required = MAX(property_value × 0.03,
                              property_value - conforming_limit)
  note: second term catches cases where loan already > conforming — handled by Gate 2

IF occupancy_type = SECOND_HOME:
  down_payment_min_pct = 0.10
  down_payment_required = property_value × 0.10

IF occupancy_type = INVESTMENT:
  down_payment_min_pct = 0.20
  down_payment_required = property_value × 0.20

conv_base_loan = property_value - MAX(down_payment_amount, down_payment_required)
conv_ltv = conv_base_loan / property_value

IF conv_ltv > 0.97 AND occupancy_type = PRIMARY:
  pass_gate_4 = false → INELIGIBLE, reason = "Conventional max LTV 97% (primary). Need 3% down minimum."
ELIF conv_ltv > 0.90 AND occupancy_type = SECOND_HOME:
  pass_gate_4 = false → INELIGIBLE, reason = "Conventional second home max LTV 90%."
ELIF conv_ltv > 0.80 AND occupancy_type = INVESTMENT:
  pass_gate_4 = false → INELIGIBLE, reason = "Conventional investment max LTV 80%."
ELSE:
  pass_gate_4 = true

DSCR:

IF occupancy_type ≠ INVESTMENT:  (already eliminated in Gate 1)
  pass_gate_4 = false

down_payment_required = property_value × 0.20
dscr_base_loan = property_value - MAX(down_payment_amount, down_payment_required)
dscr_ltv = dscr_base_loan / property_value

IF dscr_ltv > 0.80:
  pass_gate_4 = false → INELIGIBLE, reason = "DSCR max LTV 80%. Requires 20% down."
ELSE:
  pass_gate_4 = true

Cash-to-Close Check

Run for every program that passes Gate 4. This does not eliminate programs — it flags a shortfall.

FOR each program passing Gate 4:

  IF deal_type = PURCHASE:
    required_cash_to_close = MAX(down_payment_required, down_payment_amount)
                           + estimated_closing_costs
                           - seller_concession_amount

    NOTE for VA: down_payment_required = 0. VA funding fee does not require cash —
                 it is financed into the loan. Do not add to required_cash_to_close.

    IF funds_available_for_closing < required_cash_to_close:
      flag ROUTE_CTC_SHORTFALL_[PROGRAM]
      shortfall_amount = required_cash_to_close - funds_available_for_closing
      note: "Borrower is $[shortfall] short for [PROGRAM]. Consider seller concessions,
             gift funds, or DPA."

  IF deal_type IN [RATE_REFI, CASH_OUT_REFI, DEBT_CONSOLIDATION_REFI, TERM_REFI]:
    required_cash_to_close = estimated_closing_costs - seller_concession_amount
    (no down payment on refinance)

STAGE 7 — GATE 5: DSCR PRELIMINARY CHECK

Execute only if DSCR survived Gates 1–4.

IF gross_rent_monthly = null OR gross_rent_monthly = 0:
  DSCR eligibility = CONDITIONAL
  conditional_note = "No rental income data provided. Cannot compute preliminary DSCR.
                      Request market rent estimate from appraiser or borrower."
  flag ROUTE_DSCR_RENT_MISSING
  STOP Gate 5 for DSCR. Include DSCR in queue as CONDITIONAL.

Preliminary DSCR Calculation:

Step 1: Compute monthly_rate
  r = placeholder_rate / 12
  placeholder_rate = 0.0750  (7.50% — investment property premium over primary)

Step 2: Compute PMT factor
  n = 360  (30-year term)
  factor = (r × (1+r)^n) / ((1+r)^n - 1)

  Where r = 0.0750 / 12 = 0.006250
        (1 + r)^360 = (1.006250)^360 = 9.42153
        factor = (0.006250 × 9.42153) / (9.42153 - 1)
               = 0.058885 / 8.42153
               = 0.0069921

Step 3: Compute P&I
  P_and_I = dscr_base_loan × factor

Step 4: Compute monthly PITIA
  monthly_PITIA = P_and_I + monthly_tax + monthly_insurance + hoa_monthly

Step 5: Compute preliminary DSCR
  preliminary_dscr = gross_rent_monthly / monthly_PITIA

Step 6: Apply threshold
  IF preliminary_dscr ≥ 1.00:
    DSCR_PRELIM_PASS → eligibility = ELIGIBLE
  ELIF preliminary_dscr ≥ 0.85:
    DSCR_PRELIM_CONDITIONAL → eligibility = CONDITIONAL
    conditional_note = "DSCR {X.XX} < 1.00 but ≥ 0.85. Some DSCR lenders accept
                        sub-1.0 DSCR at higher rates. Flag for advisor."
    flag ROUTE_DSCR_SHORTFALL
  ELSE:
    DSCR_PRELIM_FAIL → eligibility = INELIGIBLE
    reason = "Preliminary DSCR {X.XX} below 0.85 threshold. Property cashflow
              insufficient to support loan at current terms."
    flag ROUTE_DSCR_SHORTFALL

NOTE ON ERROR HANDLING:
  IF monthly_PITIA = 0:  (invalid — should not occur after Gate 4)
    flag ROUTER_DATA_ERROR, reason = "monthly_PITIA = 0 in DSCR calculation"
    mark DSCR CONDITIONAL, require advisor review

STAGE 8 — PRELIMINARY MI AND FUNDING FEE

Compute for every ELIGIBLE or CONDITIONAL program. These are preliminary estimates — family skills compute final amounts. Flag all estimates.

VA Funding Fee

Funding fee table (2024–2026 — verify annually):
  va_funding_fee_exempt = true (disability_flag = true):
    funding_fee_pct = 0.0000
    funding_fee_amount = 0.00

  va_funding_fee_exempt = false, va_use_count = 0 (first use):
    IF down_payment_pct < 0.05:
      funding_fee_pct = 0.0215  (2.15%)
    ELIF down_payment_pct < 0.10:
      funding_fee_pct = 0.0150  (1.50%)
    ELSE:
      funding_fee_pct = 0.0125  (1.25%)

  va_funding_fee_exempt = false, va_use_count ≥ 1 (subsequent use):
    IF down_payment_pct < 0.05:
      funding_fee_pct = 0.0330  (3.30%)
    ELIF down_payment_pct < 0.10:
      funding_fee_pct = 0.0150  (1.50%)
    ELSE:
      funding_fee_pct = 0.0125  (1.25%)

Funding fee computation:
  va_base_loan = property_value - down_payment_amount
  funding_fee_amount = va_base_loan × funding_fee_pct
  va_total_loan = va_base_loan + funding_fee_amount
  va_ltv_with_fee = va_total_loan / property_value

NOTE: va_total_loan will exceed property_value when down_payment = 0 and fee > 0.
      This is normal for VA. Express va_ltv_with_fee as-is (e.g., 102.15%).
      Do not flag as an error.

FHA UFMIP and Annual MIP

FHA UFMIP:
  ufmip_rate = 0.0175  (1.75% — all LTVs, all terms)
  fha_ufmip_amount = fha_base_loan × 0.0175
  fha_total_loan = fha_base_loan + fha_ufmip_amount
  fha_ltv_base = fha_base_loan / property_value

FHA Annual MIP rate (30-year loan):
  IF fha_ltv_base > 0.95:
    annual_mip_rate = 0.0055  (0.55%)
    mip_duration = "Life of loan"
  ELIF fha_ltv_base > 0.90:
    annual_mip_rate = 0.0050  (0.50%)
    mip_duration = "Life of loan"
  ELSE:  (fha_ltv_base ≤ 0.90)
    annual_mip_rate = 0.0050  (0.50%)
    mip_duration = "11 years"

  monthly_mip = fha_base_loan × annual_mip_rate / 12

BOUNDARY PRECISION:
  LTV exactly 0.90 (= 90.00%): mip_duration = "11 years"  (≤ 0.90 → 11 years)
  LTV 0.9001 (= 90.01%): mip_duration = "Life of loan"  (> 0.90 → life of loan)
  Apply the rule as ≤ 0.90, not < 0.90.

NOTE: FHA MIP rate table above reflects rates as of March 2023 reduction.
      Flag FHA_MIP_RATE_VERIFY annually — HUD adjusts rates periodically.

Conventional PMI Estimate

IF conv_ltv ≤ 0.80:
  pmi_required = false
  monthly_pmi_estimate = 0.00

IF conv_ltv > 0.80:
  pmi_required = true

  Estimate annual PMI rate from table (conservative — actual quote from PMI provider):
  | LTV Range      | Score 740+ | Score 720–739 | Score 680–719 | Score 620–679 |
  | 90.01%–97.00%  |   0.55%     |    0.75%      |    1.00%      |    1.25%      |
  | 85.01%–90.00%  |   0.40%     |    0.55%      |    0.80%      |    1.00%      |
  | 80.01%–85.00%  |   0.28%     |    0.40%      |    0.60%      |    0.80%      |

  Score lookup:
    credit_tier 1–2  (score 740+):    use column "Score 740+"
    credit_tier 3    (score 720–739): use column "Score 720–759"
    credit_tier 4–5  (score 680–719): use column "Score 680–719"
    credit_tier 6–8  (score 620–679): use column "Score 620–679"

  monthly_pmi_estimate = conv_base_loan × annual_pmi_rate / 12

  PMI cancels when LTV reaches 80.00% — flag PMI_CANCELABLE with estimated months:
    IF conv_ltv ≤ 0.97 AND occupancy = PRIMARY:
      pmi_cancel_flag = true
      note: "PMI cancels automatically at 78% LTV per Homeowners Protection Act.
             Borrower may request cancellation at 80% LTV."

DSCR: No PMI or MI. flag MI_NOT_APPLICABLE_DSCR.

STAGE 9 — PRELIMINARY COST COMPARISON

Compute a preliminary monthly payment and cash-to-close estimate for each eligible program so the Priority stage has a basis for ordering. Use a consistent placeholder rate per program type. These numbers are estimates — family skills compute final values.

Placeholder Rates

Rate placeholders (adjust when market rates are known):
  VA:           6.50%  (typically lowest — no MI drag)
  FHA:          6.50%  (similar to VA — MI adds to payment)
  CONVENTIONAL: varies by credit_tier:
    Tier 1–2 (score 740+):   6.50%
    Tier 3   (score 720–739): 6.75%
    Tier 4–5 (score 680–719): 7.00%
    Tier 6   (score 640–679): 7.25%
    Tier 7–8 (score 620–639): 7.50%
  DSCR:         7.50%  (investment premium over primary)

PMT Factor Calculation

For any placeholder_rate and term = 30 years (360 months):

  Step 1: monthly_rate r = placeholder_rate / 12
  Step 2: compound_factor = (1 + r)^360
  Step 3: numerator = r × compound_factor
  Step 4: denominator = compound_factor - 1
  Step 5: pmt_factor = numerator / denominator

Pre-computed factors (verify with formula above if needed):
  6.50% / 12 = 0.005417  (1.005417)^360 = 6.99180  factor = 0.005417 × 6.99180 / (6.99180 - 1) = 0.0063207
  6.75% / 12 = 0.005625  (1.005625)^360 = 7.53325  factor = 0.005625 × 7.53325 / (7.53325 - 1) = 0.0064860
  7.00% / 12 = 0.005833  (1.005833)^360 = 8.11650  factor = 0.005833 × 8.11650 / (8.11650 - 1) = 0.0066530
  7.25% / 12 = 0.006042  (1.006042)^360 = 8.74477  factor = 0.006042 × 8.74477 / (8.74477 - 1) = 0.0068218
  7.50% / 12 = 0.006250  (1.006250)^360 = 9.42153  factor = 0.006250 × 9.42153 / (9.42153 - 1) = 0.0069921

NOTE: Do not compute pmt_factor as (placeholder_rate/12 × (1 + placeholder_rate/12 × placeholder_rate/12)^360).
      The correct base is (1 + r) where r = placeholder_rate/12.
      Example: for 7.00%, r = 0.005833, base = 1.005833, NOT 1.07/12 = 0.08917.

Monthly Payment Calculation Per Program

FOR each eligible program:

  P_and_I = loan_amount_for_program × pmt_factor

    Where loan_amount_for_program:
      VA:           va_total_loan  (includes funded fee)
      FHA:          fha_total_loan  (includes UFMIP)
      CONVENTIONAL: conv_base_loan
      DSCR:         dscr_base_loan

  monthly_payment_estimate = P_and_I
                           + monthly_tax
                           + monthly_insurance
                           + hoa_monthly
                           + monthly_mi  (MIP, PMI, or 0 for VA/DSCR)

  NOTE: monthly_tax, monthly_insurance, hoa_monthly are the same across all programs
        (same property, same estimated costs). Only the loan amount and MI differ.

Cash-to-Close Estimate Per Program

FOR each eligible program (PURCHASE only — refi = closing costs only):

  VA:
    ctc = estimated_closing_costs - seller_concession_amount
    note: "VA funding fee financed — $0 additional cash required for fee."

  FHA:
    ctc = down_payment_required + estimated_closing_costs - seller_concession_amount
    note: "UFMIP financed — $0 additional cash required for UFMIP."

  CONVENTIONAL:
    ctc = MAX(down_payment_amount, down_payment_required)
        + estimated_closing_costs
        - seller_concession_amount

  DSCR:
    ctc = MAX(down_payment_amount, down_payment_required)
        + estimated_closing_costs
        - seller_concession_amount

STAGE 10 — PRIORITY ORDER ASSIGNMENT

Priority 1 = evaluate first. Lower priority number = higher importance.

Priority Rules (apply in sequence — first match wins)

RULE 1 — VA ALWAYS FIRST (if eligible):
  IF VA eligibility = ELIGIBLE OR CONDITIONAL:
    VA priority = 1
  Reason: VA produces the lowest payment (no MI), lowest cash-to-close (0% down),
          and no PMI drag for life of the loan. Always benchmark against VA first.

RULE 2 — FHA BEFORE CONVENTIONAL when credit_tier ≥ 5 (score ≤ 699) AND ltv > 0.80:
  IF qualifying_credit_score ≤ 699 AND ltv > 0.80:
    FHA priority = (VA was 1) ? 2 : 1
    CONVENTIONAL priority = FHA_priority + 1
  Reason: FHA rate penalty for mid-credit is lower than conventional + PMI at these tiers.
          FHA often produces a lower total monthly payment despite UFMIP.

RULE 3 — CONVENTIONAL BEFORE FHA when credit_tier ≤ 2 (score ≥ 740) OR ltv ≤ 0.80:
  IF qualifying_credit_score ≥ 740 OR ltv ≤ 0.80:
    CONVENTIONAL priority = (VA was 1) ? 2 : 1
    FHA priority = CONVENTIONAL_priority + 1
  Reason: At high credit or low LTV, conventional pricing advantage and PMI
          cancelability outweigh UFMIP disadvantage.

RULE 4 — CONVENTIONAL BEFORE FHA when credit_tier 3–4 (score 700–739):
  IF qualifying_credit_score ≥ 700 AND qualifying_credit_score ≤ 739:
    Compare monthly_payment_estimate: FHA vs CONVENTIONAL
    Lower payment program gets lower priority number
    IF tied (within $25/month): CONVENTIONAL wins tie (PMI cancelable, UFMIP is not)

RULE 5 — DSCR ALWAYS LAST among eligible programs:
  DSCR priority = highest number in queue
  Reason: DSCR serves a different use case (investment cashflow, not income qualification).
          Always evaluate standard programs first.

RULE 6 — CONDITIONAL programs rank after ELIGIBLE of same type:
  ELIGIBLE programs of a given type always rank ahead of CONDITIONAL.

Priority Conflict Resolution

IF two programs produce identical priority by the rules above:
  Tiebreak order:
    1. ELIGIBLE beats CONDITIONAL
    2. Lower monthly_payment_estimate wins
    3. Lower required_cash_to_close wins
    4. Alphabetical: CONVENTIONAL before FHA before VA before DSCR

STAGE 11 — BUILD AND EMIT ProgramEvaluationQueue

ProgramEvaluationQueue JSON Schema

{
  "schema_version": "clarity_engine_v1.0",
  "queue_id": "PEQ_[YYYYMMDD_HHMMSS]",
  "deal_id": "DEAL_[from BorrowerProfile]",
  "borrower_id": "BORR_[from BorrowerProfile]",
  "created_at": "ISO 8601 UTC",
  "router_version": "1.0",

  "summary": {
    "programs_eligible": 0,
    "programs_ineligible": 0,
    "programs_conditional": 0,
    "no_viable_programs": false,
    "action_plan": null
  },

  "entries": [
    {
      "entry_id": "PEQ_ENTRY_[n]",
      "program": "VA | FHA | CONVENTIONAL | DSCR",
      "priority": 1,
      "eligibility": "ELIGIBLE | INELIGIBLE | CONDITIONAL",
      "ineligible_reason": null,
      "conditional_note": null,
      "flags_inherited": [],
      "preliminary": {
        "loan_amount": 0.00,
        "down_payment_required": 0.00,
        "required_cash_to_close": 0.00,
        "ltv": 0.00,
        "placeholder_rate": 0.00,
        "pmt_factor": 0.00,
        "p_and_i": 0.00,
        "monthly_tax": 0.00,
        "monthly_insurance": 0.00,
        "hoa_monthly": 0.00,
        "mi_type": "VA_FUNDING_FEE | UFMIP_PLUS_MIP | PMI | NONE",
        "mi_amount_upfront": 0.00,
        "mi_amount_monthly": 0.00,
        "mi_duration": "LIFE_OF_LOAN | 11_YEARS | CANCELABLE_AT_80PCT | N_A",
        "monthly_payment_estimate": 0.00,
        "preliminary_dscr": null
      },
      "constraints": [],
      "handoff_to_skill": "Clarity_Engine_VA_Module_SKILL | Clarity_Engine_FHA_SKILL | Clarity_Engine_Conventional_SKILL | Clarity_Engine_DSCR_SKILL"
    }
  ],

  "ineligible_programs": [
    {
      "program": "string",
      "reason": "string",
      "gate_failed": "GATE_1 | GATE_2 | GATE_3 | GATE_4 | GATE_5"
    }
  ],

  "router_flags": [],
  "warnings": []
}

No-Viable-Programs Action Plan

IF all programs are INELIGIBLE:
  no_viable_programs = true

  action_plan = build from the primary disqualifying factors:

  IF qualifying_credit_score < 500:
    "No standard mortgage program is available at current credit score ({score}).
     Action plan:
     1. Target score 500+ to unlock FHA (10% down).
     2. Target score 580+ to unlock FHA (3.5% down) and VA.
     3. Target score 620+ to unlock Conventional.
     Timeline: 90–180 days with targeted utilization paydown and
               dispute resolution of any erroneous negative items."

  IF ltv > 0.97 AND veteran_flag = false AND qualifying_credit_score ≥ 620:
    "Insufficient down payment for all standard programs.
     Required: VA (veteran only), FHA (3.5%), Conventional (3%).
     Current funds available for closing: $[X].
     Action plan:
     1. Identify DPA programs available in [state].
     2. Explore gift funds from family.
     3. Negotiate seller concessions to offset closing costs."

  IF occupancy_type = SECOND_HOME AND qualifying_credit_score < 640:
    "Second home financing requires minimum 640 score.
     Current score: [X]. Gap: [{640 - score}] points.
     Action plan: credit optimization before second home purchase."

WORKED EXAMPLE A — MARCUS & DIANA WEBB (VA Primary Path)

Input: BorrowerProfile for Marcus and Diana Webb (from Borrower Profile Skill v1.2)

qualifying_credit_score: 698   (Diana's score — lower of two middles)
credit_tier: 5
veteran_flag: true
disability_flag: false
va_use_count: 0  (first use)
occupancy_type: PRIMARY
deal_type: PURCHASE
property_type: SFR
purchase_price: 425,000
down_payment_amount: 0.00
base_loan_amount: 425,000
ltv_estimate: 1.000  (pre-fee)
down_payment_pct: 0.00
estimated_closing_costs: 12,750.00  (3% estimate)
seller_concession_amount: 0.00
funds_available_for_closing: 28,105.36
monthly_tax: 442.71
monthly_insurance: 177.08
hoa_monthly: 0.00
routing_flags: [ROUTE_CHECK_VA, ROUTE_CHECK_DPA, ROUTE_FHA_COMPETITIVE,
                ROUTE_CREDIT_OPTIMIZATION, ROUTE_DEBT_TIMING_OPPORTUNITY]

Stage 3 — Gate 1 (Occupancy):

occupancy_type = PRIMARY
  VA:           pass ✓
  FHA:          pass ✓
  CONVENTIONAL: pass ✓
  DSCR:         INELIGIBLE → "DSCR requires INVESTMENT occupancy"  [Gate 1]

Stage 4 — Gate 2 (Loan Amount):

base_loan_amount = 425,000 ≤ 806,500
  VA:           pass ✓  (no conforming limit)
  FHA:          pass ✓
  CONVENTIONAL: pass ✓
  DSCR:         already eliminated

Stage 5 — Gate 3 (Credit Score):

qualifying_credit_score = 698

  VA:   698 ≥ 580 → pass ✓
        veteran_flag = true → pass ✓
        disability_flag = false → va_funding_fee_exempt = false
        va_use_count = 0 → first use

  FHA:  698 ≥ 580 → pass ✓, fha_down_payment_tier = "3.5%"

  CONVENTIONAL: 698 ≥ 620 → pass ✓

Stage 6 — Gate 4 (LTV / Down Payment):

VA:
  down_payment_required = 0.00
  va_base_loan = 425,000 - 0 = 425,000
  ltv_before_fee = 425,000 / 425,000 = 1.000
  pass ✓ (VA no LTV cap)

FHA (3.5% down):
  down_payment_required = 425,000 × 0.035 = 14,875.00
  fha_base_loan = 425,000 - 14,875.00 = 410,125.00
  fha_ltv = 410,125.00 / 425,000 = 0.9650 = 96.50%
  0.9650 ≤ 0.965 → pass ✓ (at boundary — eligible)

  required_cash_to_close = 14,875.00 + 12,750.00 - 0 = 27,625.00
  funds_available_for_closing = 28,105.36
  27,625.00 ≤ 28,105.36 → no CTC shortfall ✓  (margin: $480.36)

CONVENTIONAL (3% min):
  down_payment_required = MAX(425,000 × 0.03, 425,000 - 806,500) = MAX(12,750, -381,500) = 12,750.00
  conv_base_loan = 425,000 - 12,750.00 = 412,250.00
  conv_ltv = 412,250.00 / 425,000 = 0.9700 = 97.00%
  0.9700 ≤ 0.97 → pass ✓ (at boundary — eligible)

  required_cash_to_close = 12,750.00 + 12,750.00 - 0 = 25,500.00
  funds_available_for_closing = 28,105.36
  25,500.00 ≤ 28,105.36 → no CTC shortfall ✓

Stage 7 — Gate 5 (DSCR): Already eliminated at Gate 1. Skip.

Stage 8 — Preliminary MI and Funding Fee:

VA Funding Fee:
  va_use_count = 0, down_payment_pct = 0.00 → funding_fee_pct = 0.0215
  va_base_loan = 425,000
  funding_fee_amount = 425,000 × 0.0215 = 9,137.50
  va_total_loan = 425,000 + 9,137.50 = 434,137.50
  va_ltv_with_fee = 434,137.50 / 425,000 = 1.0215 = 102.15%
  monthly_mi_va = 0.00  (no ongoing MI — only upfront fee, financed)

FHA UFMIP and Annual MIP:
  ufmip_amount = 410,125.00 × 0.0175 = 7,177.19
  fha_total_loan = 410,125.00 + 7,177.19 = 417,302.19
  fha_ltv_base = 410,125.00 / 425,000 = 0.9650 = 96.50%
  96.50% > 95% → annual_mip_rate = 0.0055
  monthly_mip = 410,125.00 × 0.0055 / 12 = 410,125.00 × 0.00045833 = 187.97
  mip_duration = "Life of loan"  (LTV > 90%)

Conventional PMI:
  conv_ltv = 97.00% > 80% → PMI required
  credit_tier = 5 (score 698, 680–719 band) → column "Score 680–719"
  conv_ltv = 97.00% → row "90.01%–97.00%" → annual_pmi_rate = 1.00%
  monthly_pmi = 412,250.00 × 0.0100 / 12 = 4,122.50 / 12 = 343.54
  pmi_duration = "Cancelable at 80% LTV"

Stage 9 — Preliminary Cost Comparison:

PMT FACTORS (from pre-computed table):
  VA rate placeholder = 6.50% → factor = 0.0063207
  FHA rate placeholder = 6.50% → factor = 0.0063207
  CONVENTIONAL rate placeholder = 7.00% (Tier 5) → factor = 0.0066530

VA:
  P_and_I = 434,137.50 × 0.0063207 = 2,744.04
  monthly_payment = 2,744.04 + 442.71 + 177.08 + 0.00 = 3,363.83
  cash_to_close = 12,750.00  (closing costs only)

FHA:
  P_and_I = 417,302.19 × 0.0063207 = 2,637.63
  monthly_payment = 2,637.63 + 442.71 + 177.08 + 187.97 = 3,445.39
  cash_to_close = 14,875.00 + 12,750.00 = 27,625.00

CONVENTIONAL:
  P_and_I = 412,250.00 × 0.0066530 = 2,742.72
  monthly_payment = 2,742.72 + 442.71 + 177.08 + 343.54 = 3,706.05
  cash_to_close = 12,750.00 + 12,750.00 = 25,500.00

Stage 10 — Priority Order:

Rule 1: VA is eligible → VA priority = 1
Rule 2: qualifying_credit_score = 698 ≤ 699 AND ltv = 1.00 > 0.80 → FHA before CONVENTIONAL
        FHA priority = 2
        CONVENTIONAL priority = 3

Priority order: VA (1) → FHA (2) → CONVENTIONAL (3)

Stage 11 — Handoff Statement:

PROGRAM EVALUATION QUEUE — v1.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Borrowers:  Marcus & Diana Webb  |  PURCHASE $425,000  |  Austin TX
Score:      698 (Diana controls)  |  Credit Tier 5
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ELIGIBLE PROGRAMS — 3 found

Priority 1 → VA LOAN
  Loan:        $434,137.50  (incl. $9,137.50 funding fee @ 2.15%)
  LTV:         102.15%  (normal — fee financed)
  Rate (est.): 6.50%  |  P&I: $2,744.04
  Monthly:     $3,363.83  (PITI — NO ongoing MI)
  Cash needed: $12,750.00  (closing costs only)
  ✓ Funds available: $28,105.36  (surplus $15,355.36)
  → Handoff: VA Module Skill

Priority 2 → FHA LOAN
  Loan:        $417,302.19  (incl. $7,177.19 UFMIP @ 1.75%)
  LTV:         96.50% (base)
  Rate (est.): 6.50%  |  P&I: $2,637.63
  Monthly:     $3,445.39  (PITI + $187.97 MIP — life of loan)
  Cash needed: $27,625.00  ($14,875 down + $12,750 closing)
  ✓ Funds available: $28,105.36  (surplus $480.36 — TIGHT)
  → Handoff: FHA Skill (when built)

Priority 3 → CONVENTIONAL
  Loan:        $412,250.00
  LTV:         97.00%
  Rate (est.): 7.00% (Tier 5 pricing)  |  P&I: $2,742.72
  Monthly:     $3,706.05  (PITI + $343.54 PMI — cancelable at 80% LTV)
  Cash needed: $25,500.00  ($12,750 down + $12,750 closing)
  ✓ Funds available: $28,105.36  (surplus $2,605.36)
  → Handoff: Conventional Skill (when built)

INELIGIBLE PROGRAMS — 1

  DSCR: INELIGIBLE  [Gate 1]
    Reason: Primary residence. DSCR requires investment occupancy.

ROUTER FLAGS:
  ROUTE_CHECK_VA             ← primary path (inherited from profile)
  ROUTE_CHECK_DPA            ← first-time buyer TX DPA programs — check separately
  ROUTE_CREDIT_OPTIMIZATION  ← CC utilization 70.8% — score improvement opportunity
  ROUTE_DEBT_TIMING_OPPORTUNITY ← AUTO excludes in 4 months
  FHA_CTC_MARGIN_TIGHT       ← FHA surplus only $480.36 — monitor closely

ADVISORY NOTE:
  VA produces lowest payment ($3,363.83) AND lowest cash-to-close ($12,750.00).
  VA is strongly favored for this borrower. FHA is viable but cash-to-close margin
  is $480.36 — any increase in actual closing costs makes FHA infeasible without
  additional funds or seller concession.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

WORKED EXAMPLE B — NON-VETERAN, HIGH CREDIT

Input summary:

qualifying_credit_score: 755  (Tier 2)
veteran_flag: false
occupancy_type: PRIMARY
deal_type: PURCHASE
purchase_price: 550,000
down_payment_amount: 55,000  (10%)
base_loan_amount: 495,000
ltv_estimate: 0.9000  (90.00%)
down_payment_pct: 0.10
estimated_closing_costs: 16,500  (3%)
seller_concession_amount: 0.00
funds_available_for_closing: 80,000  (sufficient)
monthly_tax: 572.92  (550,000 × 0.0125 / 12)
monthly_insurance: 229.17  (550,000 × 0.005 / 12)
hoa_monthly: 0.00

Gate summary:

VA: INELIGIBLE [Gate 3] — veteran_flag = false
DSCR: INELIGIBLE [Gate 1] — PRIMARY occupancy
FHA: pass all gates ✓
CONVENTIONAL: pass all gates ✓

Stage 8 — MI:

FHA:
  fha_base_loan = 550,000 - 55,000 = 495,000
  fha_ltv = 495,000 / 550,000 = 0.9000 = 90.00%
  ufmip = 495,000 × 0.0175 = 8,662.50
  fha_total_loan = 495,000 + 8,662.50 = 503,662.50
  fha_ltv = 90.00% → ≤ 90.00% → annual_mip_rate = 0.0050, mip_duration = "11 years"
  monthly_mip = 495,000 × 0.0050 / 12 = 2,475.00 / 12 = 206.25

CONVENTIONAL:
  conv_base_loan = 495,000
  conv_ltv = 90.00% → PMI required
  credit_tier = 2 (score 755, 720–759 band) → column "Score 720–759"
  conv_ltv 90.00% → row "85.01%–90.00%" → annual_pmi_rate = 0.55%
  monthly_pmi = 495,000 × 0.0055 / 12 = 2,722.50 / 12 = 226.88

  BOUNDARY CHECK: LTV exactly 90.00% falls in row "85.01%–90.00%"
  (boundary condition: ≤ 90.00% uses the 85-90 row, not the 90-97 row)

Stage 9 — Cost Comparison:

PMT FACTORS:
  FHA rate = 6.50% → factor = 0.0063207
  CONVENTIONAL: Tier 2, rate = 6.50% → factor = 0.0063207

FHA:
  P_and_I = 503,662.50 × 0.0063207 = 3,183.49
  monthly_payment = 3,183.49 + 572.92 + 229.17 + 206.25 = 4,191.83
  cash_to_close = 55,000.00 + 16,500.00 = 71,500.00

CONVENTIONAL:
  P_and_I = 495,000 × 0.0063207 = 3,128.75
  monthly_payment = 3,128.75 + 572.92 + 229.17 + 226.88 = 4,157.71
  cash_to_close = 55,000.00 + 16,500.00 = 71,500.00

Stage 10 — Priority:

Rule 1: VA not eligible — skip
Rule 3: credit_tier = 2 (score 740+) OR LTV ≤ 0.80?
  score 755 → Tier 2 (≥ 740) → Conventional before FHA
  CONVENTIONAL priority = 1
  FHA priority = 2

  Payment check: CONVENTIONAL ($4,157.71) < FHA ($4,191.83) ✓
  CONVENTIONAL also wins on payment — consistent with Rule 3.

Handoff Summary:

Priority 1 → CONVENTIONAL  |  $4,157.71/month  |  CTC $71,500
Priority 2 → FHA           |  $4,191.83/month  |  CTC $71,500
INELIGIBLE: VA (not veteran), DSCR (primary)

WORKED EXAMPLE C — INVESTMENT PROPERTY, DSCR TEST

Input summary:

qualifying_credit_score: 680  (Tier 5)
veteran_flag: false
occupancy_type: INVESTMENT
deal_type: PURCHASE
purchase_price: 380,000
down_payment_amount: 76,000  (20%)
base_loan_amount: 304,000
ltv_estimate: 0.8000
down_payment_pct: 0.20
estimated_closing_costs: 11,400  (3%)
gross_rent_monthly: 2,800
monthly_tax: 395.83  (380,000 × 0.0125 / 12)
monthly_insurance: 158.33  (380,000 × 0.005 / 12)
hoa_monthly: 0.00
funds_available_for_closing: 100,000  (sufficient)

Gate Summary:

VA: INELIGIBLE [Gate 1] — INVESTMENT occupancy
FHA: INELIGIBLE [Gate 1] — INVESTMENT occupancy
CONVENTIONAL: INVESTMENT overlay → 20% down required
  conv_ltv = 304,000 / 380,000 = 0.8000 = 80.00%
  0.80 ≤ 0.80 → pass Gate 4 ✓
DSCR: INVESTMENT ✓, score 680 ≥ 640 ✓, ltv 80.00% ≤ 80.00% ✓

Stage 7 — DSCR Preliminary:

dscr_base_loan = 304,000
placeholder_rate = 7.50%

Step 1: r = 0.0750 / 12 = 0.006250
Step 2: (1 + 0.006250)^360 = (1.006250)^360 = 9.42153
Step 3: numerator = 0.006250 × 9.42153 = 0.058885
Step 4: denominator = 9.42153 - 1 = 8.42153
Step 5: factor = 0.058885 / 8.42153 = 0.0069921

P_and_I = 304,000 × 0.0069921 = 2,125.61
monthly_PITIA = 2,125.61 + 395.83 + 158.33 + 0 = 2,679.77

preliminary_dscr = 2,800 / 2,679.77 = 1.0449
1.0449 ≥ 1.00 → DSCR_PRELIM_PASS → ELIGIBLE

Stage 8 — MI:

CONVENTIONAL INVESTMENT:
  conv_ltv = 80.00% → ≤ 80% → PMI not required
  monthly_pmi = 0.00

DSCR:
  No MI → monthly_mi = 0.00

Stage 9 — Cost Comparison:

CONVENTIONAL INVESTMENT (rate = 7.50% — investment premium):
  factor = 0.0069921
  P_and_I = 304,000 × 0.0069921 = 2,125.61
  monthly_payment = 2,125.61 + 395.83 + 158.33 + 0 = 2,679.77
  cash_to_close = 76,000 + 11,400 = 87,400.00

DSCR (same loan, same rate — preliminary comparison):
  P_and_I = 304,000 × 0.0069921 = 2,125.61
  monthly_PITIA = 2,125.61 + 395.83 + 158.33 = 2,679.77
  preliminary_dscr = 2,800 / 2,679.77 = 1.0449
  cash_to_close = 76,000 + 11,400 = 87,400.00

Stage 10 — Priority:

Rule 5: DSCR always last
  CONVENTIONAL priority = 1
  DSCR priority = 2

Handoff Summary:

Priority 1 → CONVENTIONAL (INVESTMENT)  |  $2,679.77/month  |  CTC $87,400
Priority 2 → DSCR  |  prelim DSCR 1.0449 PASS  |  CTC $87,400
INELIGIBLE: VA (investment), FHA (investment)

PMT FACTOR VERIFICATION TABLE

David: these are the five pre-computed factors used throughout this skill. Verify any one at any time using the formula. All five are traceable.

Verification formula (one example):

6.50%:
  r = 0.065 / 12 = 0.0054167
  (1.0054167)^360 = 6.99180
  numerator = 0.0054167 × 6.99180 = 0.037872
  denominator = 6.99180 - 1 = 5.99180
  factor = 0.037872 / 5.99180 = 0.0063207  ✓

DO NOT compute using (placeholder_rate/12)^360 or (1 + placeholder_rate × placeholder_rate/12)^360. The base must be (1 + r) where r = annual_rate / 12.

ERROR CODES

COMPANION SKILLS

Clarity Engine — Program Router Skill v1.0 | CONFIDENTIAL — PreFi, Inc. / Purpose Technology, Inc. d/b/a Purlend