Janady13/missionmatch / internal/modules/matching/intelligence/intelligence.go

1// Package intelligence derives the customer-facing screenMATCH™ "Mission Readiness" panels from the 2// pure engine output. It is PURE (no DB/IO/clock except an explicit asOf passed in) and adds NO new 3// scoring, every panel is a presentation/derivation of the same deterministic MatchResult, so the 4// AEDT explainability and reproducibility guarantees carry through unchanged. 5// 6// Panels (from the "Defining missionMATCH/screenMATCH" brief + screenMATCH User Guide): 7// - MissionReadiness : the centerpiece, operational status + the 6 named readiness categories. 8// - NextSteps : recommended actions from the band/gaps. 9// - BattleCard : strengths/gaps scouting view. 10// - ClearanceIntel : clearance intelligence layer (eligibility, investigation age, recency). 11// - ContractReadiness: satisfied requirement areas + risk areas. 12// - WinImpact : proposal-staffing win impact + reasons. 13package intelligence 14 15import ( 16 "fmt" 17 "strings" 18 "time" 19 20 "github.com/shopspring/decimal" 21 22 "github.com/missionworkforce/missionmatch/internal/modules/matching/engine" 23) 24 25var hundredVal = decimal.NewFromInt(100) 26 27// ---------- Mission Readiness (the centerpiece) ---------- 28 29// MissionReadiness rebadges the engine result into operational language. 30type MissionReadiness struct { 31 Status string `json:"status"` // "Mission Ready" | "Review Required" | "Recruiting Required" 32 StatusCode string `json:"status_code"` // "ready" | "review" | "recruiting" 33 Score string `json:"score"` // "92.00" 34 Band string `json:"band"` // green | yellow | red 35 Categories []ReadinessCategory `json:"categories"` 36} 37 38// ReadinessCategory is one named readiness dimension (the User Guide §8 breakdown). 39type ReadinessCategory struct { 40 Name string `json:"name"` // "Clearance Readiness" 41 Score string `json:"score"` // "100.00" 42 Weight string `json:"weight"` // "0.25" 43 State string `json:"state"` // "ready" (>=90) | "partial" (75-89) | "gap" (<75) 44} 45 46// engine Trace component name -> operational readiness label. 47var categoryLabels = map[string]string{ 48 "Clearance": "Clearance Readiness", 49 "Skills": "Skills Readiness", 50 "Certifications": "Certification Readiness", 51 "CustomerExperience": "Customer Readiness", 52 "Experience": "Experience Readiness", 53 "LocationAvailability": "Availability Readiness", 54} 55 56// Readiness builds the Mission Readiness panel from a match result. 57func Readiness(res engine.MatchResult) MissionReadiness { 58 cats := make([]ReadinessCategory, 0, len(res.Trace)) 59 for _, c := range res.Trace { 60 name := categoryLabels[c.Component] 61 if name == "" { 62 name = c.Component 63 } 64 cats = append(cats, ReadinessCategory{ 65 Name: name, 66 Score: c.Raw.StringFixed(2), 67 Weight: c.Weight.String(), 68 State: stateFor(c.Raw), 69 }) 70 } 71 status, code := missionStatus(res.Band) 72 return MissionReadiness{ 73 Status: status, StatusCode: code, Score: res.Total.StringFixed(2), 74 Band: res.Band.Code(), Categories: cats, 75 } 76} 77 78// MissionStatusLabel is the operational status label for a band ("Mission Ready", etc.). 79func MissionStatusLabel(b engine.Band) string { l, _ := missionStatus(b); return l } 80 81func missionStatus(b engine.Band) (label, code string) { 82 switch b { 83 case engine.BandGreen: 84 return "Mission Ready", "ready" 85 case engine.BandYellow: 86 return "Review Required", "review" 87 default: 88 return "Recruiting Required", "recruiting" 89 } 90} 91 92// stateFor classifies a 0-100 sub-score using the same band thresholds as the total. 93func stateFor(score decimal.Decimal) string { 94 switch { 95 case score.GreaterThanOrEqual(engine.BandGreenMin): 96 return "ready" 97 case score.GreaterThanOrEqual(engine.BandYellowMin): 98 return "partial" 99 default: 100 return "gap" 101 } 102} 103 104// ---------- Recommended Next Steps ---------- 105 106// NextStep is a recommended action shown after evaluation. 107type NextStep struct { 108 Action string `json:"action"` 109 Reason string `json:"reason"` 110} 111 112// NextSteps recommends actions from the band (User Guide §12). 113func NextSteps(res engine.MatchResult) []NextStep { 114 switch res.Band { 115 case engine.BandGreen: 116 return []NextStep{ 117 {"Move to Candidate Slate", "Candidate is proposal ready."}, 118 {"Add to Talent Pipeline", "Retain for future opportunities."}, 119 } 120 case engine.BandYellow: 121 return []NextStep{ 122 {"Request Interview", "Additional validation recommended."}, 123 {"Review Gaps", "Resolve gaps before submission."}, 124 {"Add to Talent Pipeline", "Suitable for future opportunities."}, 125 } 126 default: 127 return []NextStep{ 128 {"Recruit Additional Candidates", "Qualification gaps identified."}, 129 {"Add to Talent Pipeline", "Reconsider for better-fit opportunities."}, 130 } 131 } 132} 133 134// ---------- Battle Card ---------- 135 136// BattleCard is the scouting-report view (User Guide §9). 137type BattleCard struct { 138 Strengths []string `json:"strengths"` 139 Gaps []string `json:"gaps"` 140} 141 142// BattleCardFor derives strengths (✓) and gaps (⚠) from the candidate + result. 143func BattleCardFor(c engine.Candidate, r engine.Requirement, res engine.MatchResult) BattleCard { 144 var strengths []string 145 146 if res.Clearance.GreaterThanOrEqual(hundredVal) && c.Clearance.Level >= engine.ClearanceConfidential { 147 strengths = append(strengths, fmt.Sprintf("%s %s", c.Clearance.Level.String(), c.Clearance.Status.String())) 148 } 149 for _, m := range res.MatchedSkills { 150 if m.Matched { 151 strengths = append(strengths, m.RequiredSkillName) 152 } 153 } 154 if res.CustomerExperience.GreaterThanOrEqual(hundredVal) && r.CustomerAgency != "" { 155 strengths = append(strengths, fmt.Sprintf("%s experience", r.CustomerAgency)) 156 } 157 if r.RequiredYears > 0 && c.YearsExperience >= r.RequiredYears { 158 strengths = append(strengths, fmt.Sprintf("Exceeds experience requirement (%d yrs)", c.YearsExperience)) 159 } 160 // Held certifications that the requirement asked for. 161 held := lowerSet(c.Certifications) 162 for _, rc := range r.RequiredCerts { 163 if held[lower(rc)] { 164 strengths = append(strengths, rc) 165 } 166 } 167 168 gaps := append([]string{}, res.GapSummary...) // unmet mandatory items (empty slice, never null) 169 return BattleCard{Strengths: dedupe(strengths), Gaps: gaps} 170} 171 172// ---------- Clearance Intelligence ---------- 173 174// ClearanceFacts is the clearance input (carries dates the engine deliberately omits). 175type ClearanceFacts struct { 176 Level engine.ClearanceLevel 177 Poly engine.Polygraph 178 Status engine.ClearanceStatus 179 GrantedAt *time.Time 180 ExpiresAt *time.Time 181 ReinvestigationDueAt *time.Time 182 CustomerAgencies []string 183 // Provenance records HOW the clearance is known (self_reported is the default and honest baseline); 184 // the platform never verifies a clearance itself. VerifiedAt is set when an FSO or sponsor confirmed. 185 Provenance string 186 VerifiedAt *time.Time 187} 188 189// ClearanceIntel is the clearance intelligence layer (Evolution #6). 190type ClearanceIntel struct { 191 Current string `json:"current"` // "TS/SCI" 192 Status string `json:"status"` // "Active" 193 SCIEligible bool `json:"sci_eligible"` // TS or above 194 CIPolyEligible bool `json:"ci_poly_eligible"` 195 FullScopePoly bool `json:"full_scope_poly"` 196 Expired bool `json:"expired"` 197 InvestigationAgeMonths *int `json:"investigation_age_months,omitempty"` 198 ExpiresAt *string `json:"expires_at,omitempty"` 199 ReinvestigationDueAt *string `json:"reinvestigation_due_at,omitempty"` 200 RecentClassifiedSupport bool `json:"recent_classified_support"` 201 // Provenance and honesty: the platform never verifies a clearance, it records how the clearance is 202 // known. Verified is true ONLY when an FSO or sponsor confirmed it (the authoritative DISS check), 203 // never because the platform checked. The default self_reported reads "self reported, not verified". 204 Provenance string `json:"provenance"` // self_reported | sponsor_verified | document | continuous_vetting 205 ProvenanceLabel string `json:"provenance_label"` // human label 206 Verified bool `json:"verified"` // true only for a sponsor FSO verification 207 VerifiedAt *string `json:"verified_at,omitempty"` 208} 209 210// provenanceLabel maps a clearance provenance code to honest UI copy. Self reported is never "verified". 211func provenanceLabel(p string) string { 212 switch p { 213 case "sponsor_verified": 214 return "Sponsor FSO verified" 215 case "document": 216 return "Document on file, not FSO verified" 217 case "continuous_vetting": 218 return "Continuous vetting enrolled" 219 default: 220 return "Self reported, not verified" 221 } 222} 223 224// Clearance derives the clearance intelligence as-of a date. 225func Clearance(f ClearanceFacts, asOf time.Time) ClearanceIntel { 226 ci := ClearanceIntel{ 227 Current: f.Level.String(), 228 Status: f.Status.String(), 229 SCIEligible: f.Level >= engine.ClearanceTopSecret, 230 CIPolyEligible: f.Poly >= engine.PolyCI, 231 FullScopePoly: f.Poly == engine.PolyFullScope, 232 RecentClassifiedSupport: len(f.CustomerAgencies) > 0, 233 } 234 if f.ExpiresAt != nil { 235 ci.Expired = f.ExpiresAt.Before(asOf) 236 s := f.ExpiresAt.Format("2006-01-02") 237 ci.ExpiresAt = &s 238 } 239 if f.Status == engine.StatusExpired { 240 ci.Expired = true 241 } 242 if f.ReinvestigationDueAt != nil { 243 s := f.ReinvestigationDueAt.Format("2006-01-02") 244 ci.ReinvestigationDueAt = &s 245 } 246 if f.GrantedAt != nil { 247 m := monthsBetween(*f.GrantedAt, asOf) 248 ci.InvestigationAgeMonths = &m 249 } 250 prov := f.Provenance 251 if prov == "" { 252 prov = "self_reported" 253 } 254 ci.Provenance = prov 255 ci.ProvenanceLabel = provenanceLabel(prov) 256 ci.Verified = prov == "sponsor_verified" // only an FSO confirmation counts as verified, never the platform 257 if f.VerifiedAt != nil { 258 s := f.VerifiedAt.Format("2006-01-02") 259 ci.VerifiedAt = &s 260 } 261 return ci 262} 263 264// ---------- Contract Readiness ---------- 265 266// RequirementArea is one contract requirement category and whether the candidate satisfies it. 267type RequirementArea struct { 268 Area string `json:"area"` 269 Met bool `json:"met"` 270} 271 272// RiskArea is a flagged staffing risk. 273type RiskArea struct { 274 Severity string `json:"severity"` // "warning" | "info" 275 Message string `json:"message"` 276} 277 278// ContractReadiness lists satisfied requirement areas + risk areas (Evolution #3). 279type ContractReadiness struct { 280 Areas []RequirementArea `json:"areas"` 281 Risks []RiskArea `json:"risks"` 282} 283 284// Contract derives contract readiness. expiringWindow is how soon a clearance expiry is a risk. 285func Contract(c engine.Candidate, r engine.Requirement, res engine.MatchResult, f ClearanceFacts, asOf time.Time) ContractReadiness { 286 areas := []RequirementArea{ 287 {"Labor Category Requirements", res.Skills.GreaterThanOrEqual(engine.BandYellowMin)}, 288 {"Clearance Requirements", res.Clearance.GreaterThanOrEqual(hundredVal)}, 289 {"Certification Requirements", res.Certifications.GreaterThanOrEqual(hundredVal)}, 290 {"Customer Experience Requirements", res.CustomerExperience.GreaterThanOrEqual(hundredVal)}, 291 {"Availability Requirements", res.Location.GreaterThanOrEqual(engine.BandGreenMin)}, 292 } 293 294 risks := []RiskArea{} // empty slice, never null 295 if f.ExpiresAt != nil { 296 days := int(f.ExpiresAt.Sub(asOf).Hours() / 24) 297 switch { 298 case days < 0: 299 risks = append(risks, RiskArea{"warning", "Clearance is expired."}) 300 case days <= 90: 301 risks = append(risks, RiskArea{"warning", fmt.Sprintf("Clearance expires in %d days.", days)}) 302 } 303 } 304 if len(f.CustomerAgencies) == 0 { 305 risks = append(risks, RiskArea{"warning", "No recorded classified/customer program support."}) 306 } 307 if r.RequiredYears > 0 && c.YearsExperience < r.RequiredYears { 308 risks = append(risks, RiskArea{"info", fmt.Sprintf("Experience below requirement (%d of %d years).", c.YearsExperience, r.RequiredYears)}) 309 } 310 if f.ReinvestigationDueAt != nil && f.ReinvestigationDueAt.Before(asOf) { 311 risks = append(risks, RiskArea{"warning", "Periodic reinvestigation is overdue."}) 312 } 313 return ContractReadiness{Areas: areas, Risks: risks} 314} 315 316// ---------- Win Impact ---------- 317 318// WinImpact is the proposal-staffing win impact (Evolution #2). 319type WinImpact struct { 320 Level string `json:"level"` // "High Impact" | "Medium Impact" | "Low Impact" 321 LevelCode string `json:"level_code"` // high | medium | low 322 StaffingStrength string `json:"staffing_strength"` // "92.00" 323 Reasons []string `json:"reasons"` 324} 325 326// Win derives the win impact + reasons. 327func Win(c engine.Candidate, r engine.Requirement, res engine.MatchResult) WinImpact { 328 // A non nil empty slice so JSON encodes [] not null when nothing fires; the client maps over it. 329 reasons := []string{} 330 if c.Clearance.Level == engine.ClearanceTSSCI && c.Clearance.Status == engine.StatusActive { 331 reasons = append(reasons, "Active TS/SCI") 332 } 333 if res.CustomerExperience.GreaterThanOrEqual(hundredVal) && r.CustomerAgency != "" { 334 reasons = append(reasons, fmt.Sprintf("Prior %s / similar program experience", r.CustomerAgency)) 335 } 336 if r.KeyPersonnel && res.Band == engine.BandGreen { 337 reasons = append(reasons, "Matches Key Personnel requirements") 338 } 339 if r.RequiredYears > 0 && c.YearsExperience > r.RequiredYears { 340 reasons = append(reasons, "Exceeds required experience") 341 } 342 if res.Clearance.GreaterThanOrEqual(hundredVal) { 343 reasons = append(reasons, "Meets clearance requirement") 344 } 345 346 level, code := "Low Impact", "low" 347 switch res.Band { 348 case engine.BandGreen: 349 level, code = "High Impact", "high" 350 case engine.BandYellow: 351 level, code = "Medium Impact", "medium" 352 } 353 return WinImpact{Level: level, LevelCode: code, StaffingStrength: res.Total.StringFixed(2), Reasons: reasons} 354} 355 356// ---------- helpers ---------- 357 358// monthsBetween returns whole calendar months from a to b (>= 0). 359func monthsBetween(a, b time.Time) int { 360 m := int(b.Year()-a.Year())*12 + int(b.Month()) - int(a.Month()) 361 if b.Day() < a.Day() { 362 m-- 363 } 364 if m < 0 { 365 m = 0 366 } 367 return m 368} 369 370func lower(s string) string { return strings.ToLower(strings.TrimSpace(s)) } 371 372func lowerSet(items []string) map[string]bool { 373 m := make(map[string]bool, len(items)) 374 for _, it := range items { 375 m[lower(it)] = true 376 } 377 return m 378} 379 380func dedupe(items []string) []string { 381 seen := make(map[string]bool, len(items)) 382 out := make([]string, 0, len(items)) 383 for _, it := range items { 384 if !seen[it] { 385 seen[it] = true 386 out = append(out, it) 387 } 388 } 389 return out 390} 391