Janady13/missionmatch / docs/superpowers/specs/2026-06-29-w3-ai-staffing-recommendations-design.md

1# W3 AI Staffing Recommendations, design 2 3Date: 2026-06-29. Workstream: W3, on the missionMATCH platform. Builds on W0 (AEDT 4compliance foundation), W1 (Mission Check), W2 (Revenue at Risk command center), 5slateMATCH (slate generation), and the AI intelligence layer (the `internal/modules/ai` 6package and the stateless MEGAMIND inference plane). 7 8## 1. Purpose 9 10slateMATCH already scores and ranks candidates per requirement, and the W2 command center 11already names the staffing gaps and their dollar exposure. The missing layer is the one 12that turns that scored candidate by requirement matrix into explained, recommended actions 13that a human approves or rejects. W3 is that layer. 14 15It serves three views, all of one recommendation core: 16 171. Close the named gaps. For each gap the command center names, the concrete way to close 18 it: assign an available candidate, reskill a near miss who holds an adjacent skill, 19 reassign a strong fit from a lower priority requirement, or flag for external sourcing. 202. Optimize the whole bench. Allocate the bench across all open requirements at once to 21 maximize revenue protected, surfacing the contention when one scarce candidate tops 22 several gaps. 233. Proactive matching. Per available candidate, the best fit opportunities, plus a standing 24 watch that alerts when a newly available or newly certified candidate unlocks a gap that 25 was previously unfillable. 26 27## 2. Non negotiable constraints, and how W3 holds each 28 291. No Python anywhere. W3 is pure Go. The optimizer is a pure Go minimum cost flow solver, 30 no cgo, no native math library. Any generation runs out of process on the existing 31 MEGAMIND plane over HTTP. 322. FIPS intact. The API binary stays `CGO_ENABLED=0 GOFIPS140=v1.0.0`. The optimizer adds 33 no dependency and no cgo. The FIPS stamp is verified after every build. 343. EEO isolation absolute. The recommendation core reads no demographic field. The 35 `internal/modules/ai` EEO unreachability tripwire (`TestNoAIFileReferencesEEO`) extends 36 to every new W3 source file, and a new test asserts the recommendation core takes no 37 protected attribute as input. `safety.ForbidEEO` guards every string sent to the plane. 384. Tenant isolation. W3 runs entirely inside `RunInTenantTx`, RLS scoped, on the validated 39 org from the session. The MEGAMIND plane stays stateless and persists nothing about any 40 recommendation. 415. The deterministic engine is the floor. Eligibility, the six component scores, the band, 42 and the rank within a gap come only from `engine.ScoreCandidate`. W3 never recomputes a 43 score and never overrides one. The optimizer arbitrates allocation among candidates the 44 engine already qualified, it never qualifies or disqualifies anyone. 456. Explainable, human in the loop, never auto reject. Every recommendation traces to frozen 46 engine numbers and explicit rules. A person approves or rejects each one. Rejecting an 47 assign recommendation only dismisses that suggestion, it never blacklists the candidate. 48 A source recommendation is a gap coverage note, never a decision about a person. 497. Both cloud portable. No cloud specific primitive. The proactive refresh uses the existing 50 scheduled job pattern (cron on the host or a systemd timer) with Postgres side change 51 detection, no Kafka, SQS, or Event Grid. 52 53## 3. The recommendation core 54 55Input: the org's open requirements (the W2 gaps) and the bench. The core asks the engine to 56score the relevant candidate by requirement pairs (reusing `engine.ScoreCandidate`, 57persisting each to `candidate_evaluations` so the score is frozen and referenceable), then 58adds four deterministic outputs on top of that frozen matrix. 59 60### 3.1 Action classification (deterministic) 61 62For a candidate against a gap, the recommended action is decided by explicit rules, in this 63order: 64 65- `ASSIGN`: the candidate is available, clears the band threshold (Green, or Yellow if the 66 org allows Yellow staffing, configurable, default Yellow 75 and up), and is not already 67 committed to a higher priority requirement. 68- `REASSIGN`: the candidate clears the band but is currently committed to a lower priority 69 or lower dollar requirement than this gap. The recommendation names both requirements and 70 the priority delta. 71- `RESKILL`: the candidate falls short only on the skills component, is otherwise eligible 72 (clearance, availability), and holds a skill adjacent to a missing required skill above the 73 adjacency threshold, found through the live `scaffolds.SkillAdjacency` over the 74 `skills.embedding` HNSW index. The recommendation names the held skill, the missing skill, 75 and the adjacency distance. 76- `SOURCE`: after the eligible bench is exhausted for the open slots, the remaining slots 77 recommend external sourcing. This is a gap coverage note, it names no candidate and rejects 78 no one. 79 80`TEAM` (recommend a partner or subcontractor through the teaming graph) is out of scope for 81v1 because GraphRAG teaming is still a scaffold. The action enum reserves the value so the 82schema does not change when it lands. 83 84### 3.2 Ranking and confidence (deterministic) 85 86Within a gap, recommendations rank by the engine total descending, then by action priority 87(assign, reassign, reskill, source), then by candidate id for a stable order. 88 89Confidence is derived deterministically, not learned: a function of the engine score margin 90above the band floor, the clearance provenance (self reported scores lower than sponsor 91verified or continuous vetting), and data completeness (a profile missing customer history 92scores lower confidence). It is a transparency aid, never a probability and never an input 93to the decision. The learned LTR reranker with SHAP from the AI layer Phase 8 stays a 94sequenced future layer, it is not part of W3 v1. 95 96### 3.3 Narrative (the only place the AI is used) 97 98The orchestrator writes the human readable rationale for each recommendation, grounded only 99in the engine component trace, the adjacency facts for a reskill, availability, and the 100current assignment. It is faithfulness gated through the existing `inference.Client` 101faithfulness check. If the gate cannot confirm the generated rationale against those facts, 102the recommendation falls back to a deterministic rationale string assembled from the same 103facts and records `rationale_source = deterministic`. The recommendation itself never 104depends on the AI, so a plane outage (handled by the existing circuit breaker) degrades the 105prose, never the correctness. 106 107## 4. The three views 108 109### 4.1 Close the named gaps (gap centric) 110 111A command center gap (a labor category, a required clearance, a skill set, and a slot count) 112resolves to its backing open requirement row, or rows where one labor category spans several 113open requirements. The core scores the eligible bench against that requirement, classifies 114and ranks the actions, and returns the ranked list. This is a direct read of the core for one 115requirement. 116 117### 4.2 Optimize the whole bench (portfolio, true optimizer) 118 119Allocate the bench across all open requirements at once to maximize revenue protected. 120 121Formulation, a maximum profit assignment solved as a pure Go minimum cost flow: 122 123- Nodes: a source, one node per eligible candidate, one node per open requirement, a sink. 124- Edges: 125 - source to each candidate, capacity 1, cost 0 (a candidate is assigned at most once). 126 - candidate i to requirement j, capacity 1, present only if the engine qualified i for j 127 (band at or above the staffing floor). The cost is the negative of the assignment value. 128 - requirement j to the sink, capacity equal to the open slot count for j, cost 0. 129- Assignment value of i to j: a function of the frozen engine total (fit) and the 130 requirement priority (a function of the opportunity value or exposure and the readiness 131 impact). Values are scaled to int64 with a fixed precision and deterministic rounding so 132 the flow solver stays integer exact. Scoring stays decimal in the engine, only the 133 optimizer objective uses scaled integers, and that is an allocation step, not a score. 134- Solve by successive shortest path augmentation, stopping when the next augmenting path has 135 non negative cost (no further profitable assignment). Ties are broken by a fixed node order 136 (candidate id, then requirement id) so the result is deterministic. Unfilled slots and 137 unassigned candidates are allowed and natural in this formulation, unfilled slots become 138 `SOURCE` recommendations. 139 140The optimizer never qualifies or disqualifies a candidate. Exclusion from an assignment is 141always either the engine's deterministic band (not eligible) or the optimizer arbitrating 142contention among the qualified to maximize the transparent objective. 143 144Per assignment explanation, computed from the solution, not from dual or shadow prices: 145 146- The assigned candidate's engine score for the assigned requirement (why qualified). 147- The candidate's next best alternative requirement and the value delta (the opportunity 148 cost of placing them here). 149- The requirement's next best candidate if this one were removed, and the score delta (why 150 this candidate over the next). 151 152The AI narrates that counterfactual in plain language, faithfulness gated against the 153computed numbers. Example: "Assigned J. Okafor to the intelligence analyst gap. They also 154qualified for the targeting gap at 88, but targeting is well covered by R. Vance at 88 while 155the intelligence analyst gap has no comparable backup, so this allocation protects 0.6M 156dollars more." 157 158### 4.3 Proactive matching (candidate centric, plus a watch) 159 160For each available candidate, the best fit open opportunities, ranked by engine total. A 161scheduled recompute (section 7) detects changes to availability, certifications, clearance 162status, or new opportunity ingestion, and raises an alert when a change unlocks a gap that 163had no eligible bench before. The alert is a recommendation row with the triggering change 164recorded. 165 166## 5. Persistence 167 168Two new RLS forced tables, org scoped, composite foreign keys, candidate scoped for erasure. 169 170`recommendation_runs`: id, organization_id, view (enum gap, portfolio, proactive), scope_ref 171(the requirement id for a gap run, null for portfolio, the candidate id for a proactive run), 172model_version (the frozen engine version plus the W3 logic version), created_by, created_at, 173parameters (JSON, the thresholds and the staffing floor used). 174 175`staffing_recommendations`: id, organization_id, run_id (foreign key to recommendation_runs), 176requirement_id, candidate_id (null for source), action (enum assign, reassign, reskill, 177source, team), rank, confidence (decimal), engine_evaluation_id (foreign key to 178candidate_evaluations, the frozen score), value_score (the int64 scaled optimizer value for a 179portfolio run, null otherwise), rationale (text), rationale_source (enum ai_faithful, 180deterministic), evidence (JSON, the adjacency facts for a reskill, the reassign source 181requirement, or the portfolio counterfactual), status (enum pending, approved, rejected, 182dismissed, superseded), decided_by, decided_at, decision_note, created_at. The decision 183columns mirror `slate_members` so the existing approve and reject UI and audit pattern carry 184over. Erasure (`sourcing.Delete` and the anonymize in place path) nulls or removes a 185candidate's recommendation rows, joining the existing `Memory.ForgetCandidate` cleanup. 186 187Migration number follows the current head (the AI layer left the shared database at goose 188v17, so this is 0018, plus the matching eeo set unchanged). 189 190## 6. Determinism boundary, restated for the spec reader 191 192The decision content of every recommendation (who, what action, what rank, what confidence, 193and for the portfolio view which requirement) is computed only from frozen engine outputs, 194the explicit action rules, the skill adjacency, availability, current assignment, and the 195deterministic optimizer. No model sits in that path. The AI produces only the natural 196language rationale, and only when the faithfulness gate confirms it against those same facts. 197 198## 7. Triggers and refresh (both cloud portable) 199 200- On demand: the gap and portfolio views compute on request. 201- Proactive watch: a scheduled recompute, run by the existing host cron or a systemd timer 202 (the same pattern as `mm-opp-sync` and `mm-sam-sync`), no cloud specific event service. It 203 detects relevant changes through Postgres side comparison (a candidate or opportunity 204 updated since the last run), recomputes affected scopes, and writes new recommendation rows 205 and alerts. The recompute is idempotent and writes a fresh run rather than mutating prior 206 rows (prior rows move to `superseded`). 207 208## 8. AEDT audit and the human in the loop flow 209 210- A run emits `aedt.staffing.recommended` on the tenant transaction: run id, view, scope ref, 211 per action counts, model version. No PII, no names, no demographics, no rationale text. 212- A human decision emits `aedt.staffing.decided`: the recommendation id, the action, the 213 decision, and a has_note flag. The note text is never in the payload (the slate decision 214 convention). 215- Approving an assign recommendation can flow into the existing slate decision (link the 216 recommendation to a slate member) or record the assignment, depending on whether a slate 217 exists for the requirement. Rejecting only dismisses the suggestion. Never auto reject 218 holds throughout, the system proposes, a person disposes. 219 220## 9. EEO safety 221 222- The recommendation core, the action classifier, the optimizer, and the value function take 223 no demographic input and reference no eeo table or column. sqlc models no eeo table, so the 224 new queries cannot name one. 225- `safety.ForbidEEO` guards every string passed to the plane for narration. 226- `TestNoAIFileReferencesEEO` (the existing tripwire) walks the new W3 source files and fails 227 if any executable line references the eeo schema. 228- A new test asserts the recommendation core's public input types contain no protected 229 attribute field, the same shape as the existing engine `Candidate` no demographic test. 230 231## 10. API surface 232 233New routes under the tenant scoped group, behind the session resolver, CSRF, RBAC, and the 234same audit. Mounted under the `slatematch` and `missionmatch` namespaces as fits the view. 235 236- `POST /recommendations/gap/{requirementID}` returns the ranked actions for one gap. 237- `POST /recommendations/portfolio` returns the optimized allocation with per assignment 238 explanations. 239- `GET /recommendations/proactive` returns the current bench watch alerts and per candidate 240 best fits. 241- `POST /recommendations/{recommendationID}/decision` records approve, reject, or dismiss 242 (the slate decision pattern). 243 244RBAC: a new capability `staffing.recommend` (granted to the roles that already hold 245`slate.edit`) gates the three generating endpoints. The decision endpoint reuses the slate 246decision capability. Read of recommendations reuses `candidate.read`. 247 248## 11. Frontend 249 250- Command center: each named gap gets a recommended actions expander (the gap centric view), 251 and the staffing gaps panel gets an optimize bench action that opens the portfolio 252 allocation view with the per assignment explanations and the contention notes. 253- Candidates page: a bench watch panel (the proactive alerts) and a per candidate best fits 254 section. 255- New TanStack Query hooks in the slatematch and missionmatch query modules, with approve, 256 reject, and dismiss mutations that invalidate the command center and candidates caches. 257- The decision UI reuses the slate member approve and reject component, including the note 258 input. 259 260## 12. Testing strategy 261 262- Unit, pure logic, no database: 263 - The action classifier: golden cases for assign, reassign, reskill, source, including the 264 band floor boundary and the adjacency threshold boundary. 265 - The optimizer: determinism (same input, same allocation), correctness on small hand 266 checked instances, tie breaking, unfilled slots become source, and a property test that 267 no assigned candidate was below the engine band floor. 268 - Confidence: monotonic in score margin and provenance. 269- Unit, safety: 270 - The EEO unreachability tripwire extended to the W3 files. 271 - The no protected attribute input test on the core types. 272- Integration on M4 (the `integration` build tag, against the live Postgres): 273 - End to end gap view, portfolio view, and proactive view against seeded data, asserting 274 every recommendation references a real frozen `candidate_evaluations` row. 275 - The faithfulness fallback path (force an unfaithful narrative, assert 276 `rationale_source = deterministic` and the recommendation still stands). 277 - Erasure removes a candidate's recommendations. 278 - The decision flow writes `aedt.staffing.decided` and never auto rejects. 279- Build gates: FIPS stamp after build, `make ci-gates`, the backdoor and EEO gates green. 280 281## 13. Out of scope for v1, sequenced 282 283- `TEAM` recommendations through the teaming graph (waits on GraphRAG teaming leaving 284 scaffold). 285- The learned LTR reranker with SHAP on top of the engine (waits on labeled decision history, 286 the AI layer Phase 8 sequencing). 287- A learned confidence or win probability (waits on labeled win and loss history, the AI 288 layer Phase 9 sequencing). 289- Auto creation of training plans for a reskill recommendation (v1 names the gap and the 290 adjacency, it does not author a curriculum). 291 292## 14. Decisions made during design 293 294- Scope: all three views, built as one recommendation core seen from three angles, not three 295 separate features. 296- Portfolio allocation: a true optimizer (pure Go minimum cost flow), not an explainable 297 greedy heuristic. Explainability is preserved by keeping eligibility deterministic in the 298 engine and by generating a plain language counterfactual per assignment from the value 299 matrix rather than exposing solver internals. 300- The AI is confined to narration behind a faithfulness gate, with a deterministic fallback. 301 No model is in the decision path. 302