# Credit Score Calibration & Monitoring

## Purpose

This report measures how immutable application-time credit scores relate to later approval and repayment outcomes. It is evidence for future calibration work, not a second scoring engine and not an approval rule.

The V1 scoring formula remains unchanged. Any future V2 must be introduced explicitly as a new score version and must not rewrite historical V1 snapshots.

## Cohort Source

A loan is included only when it has `application_credit_score_history_id` linked to an immutable `customer_credit_score_histories` row.

The report groups the loan by the score band and score version captured when the application entered review. It does not regroup historical applications using the customer's latest score.

## Outcome Definitions

### Application outcome

- **Approved**: `approved_at` exists, or the loan has progressed to an approved/post-approval status.
- **Rejected**: current loan status is `rejected`.
- **Pending**: neither approved nor rejected.
- **Approval rate**: approved / (approved + rejected). Pending applications are excluded from the denominator.

Approval rate is descriptive. Because staff can see the score during review, approval outcome is not an independent measure of model quality and must not be used alone to recalibrate the model.

### Repayment observation

A loan becomes observable for repayment monitoring after activation or after it reaches a repayment/closed/write-off status.

- **Current arrears**: active loan with overdue balance or days overdue.
- **Serious arrears**: active loan at or above `credit_score.thresholds.repayment.serious_arrears_days` (currently 30 days).
- **Current arrears rate**: current overdue / current outstanding for active loans in the cohort.
- **Write-off rate**: written-off observed loans / all observed repayment loans.

Recent cohorts may not have had enough time to mature into late-payment or write-off outcomes. Compare cohorts with similar observation age before making policy conclusions.

## Score Migration

Migration compares the immutable application score with the customer's latest current score.

Band movement is classified as improved, stable, or worsened only when the application score and current score use the same scoring version. Cross-version comparisons are counted separately so a future V2 scale/formula change is not mistaken for customer credit movement.

## Drift Monitoring

Drift monitoring compares application-score distributions from a recent window with the immediately preceding window for the same score version.

Defaults live in `config/credit_score.php`:

- recent window: 90 days;
- minimum sample per window: 20 applications;
- average-score warning: 25 points;
- score-band share warning: 15 percentage points.

These are operational monitoring thresholds only. They do not affect score calculation, risk overlays, permissions, or loan decisions.

A drift status is:

- `insufficient_data` when either comparison window is below the configured minimum sample;
- `warning` when sufficient data exists and a configured score/distribution threshold is crossed;
- `stable` when sufficient data exists and no configured threshold is crossed.

## Branch Isolation

The controller resolves branch IDs through `BranchAccessService`. The report service receives only those authorized branch IDs and every application-score query is filtered by `loans.branch_id` before aggregation.

CSV export uses the same branch resolution path as the HTML report.

## Calibration Guardrails

1. Do not use gender, age/date of birth, marital status, religion, ethnicity, geographic location, NIN availability, or similar personal traits for calibration.
2. Do not change V1 weights or thresholds because of a small sample or a single branch result.
3. Do not interpret approval rate as pure model performance; approval decisions may already be influenced by the score and other manual review information.
4. Treat thin-file and low-confidence cohorts separately when interpreting results.
5. Require enough repayment observation before comparing default/write-off outcomes.
6. Review branch operational differences before assuming score drift is model drift.
7. Introduce any approved recalibration as a new version with tests, documentation, audit history, and preserved historical V1 rows.

## V2 Readiness

A V2 proposal should only be prepared after management has enough representative repayment outcomes across score bands and branches to identify a repeatable calibration issue. The report intentionally does not generate or apply new weights automatically.
