​

ATS Stage Routing

​

Overview

​

All Routing Events and Their Pipelines

Resume review is handled by a separate method (handle_resume_stage_movement) that has additional preconditions (application must be in start stage to move) and does not go through _handle_stage_movement_for_target. It is not currently routed via routing rules. Exception: if a prior resume-pass write already landed (retry after a failed Tenzo OUTREACH / OUTREACH_PAUSED transition), the handler reports applied even when the application is already outside the start stage, so the throwaway outreach ATS write stays skipped.

PENDING_ACCOMMODATION_REVIEW is a stage overlay, not a call-status hold. The call keeps its real terminal CallStatus; nothing is parked and nothing is deferred. The normal terminal transition (CALL_COMPLETED / FAILED_KNOCKOUT) runs first and owns all ordinary post-call effects — results posting, notifications, tasks, scheduling, billing, and the AI_INTERVIEW_PASSED / AI_INTERVIEW_FAILED ATS move. Only after that transition commits does transition_work_accommodation_review_stage_if_needed overlay the review stage on top, gated by the ownership CAS (expected_latest_history_call_id) so an older call cannot put a newer call’s outcome into review. The overlay stage is the only record that review is pending: there is no parallel durable marker, so an application not on PENDING_ACCOMMODATION_REVIEW is not held. Overlay gate (should_overlay_work_accommodation_review) requires all three:

1. final_status == COMPLETED. A FAILED_KNOCKOUT call is never overlaid, and a non-terminal call (INCOMPLETE / RESCHEDULED) stays on its normal retry path — detection re-fires on the next completed attempt, so an unresolved flag is never lost.
2. Unresolved review items exist on the persisted grades (grades_need_work_accommodation_review), with the job’s setting enabled.
3. InterviewPassEvaluation.review_could_change_outcome — i.e. passed is not False. Flagged questions already carry provisional full credit (apply_provisional_full_credit), so a definite fail under that ceiling cannot be reversed by review and takes the ordinary below-threshold path instead (INFO questions are flagged for review and dismissal only without provisional score modifications). Unknown (None — no configured ATS client, or a transient lookup failure) is treated conservatively as “could still change”.

Resolution releases the stage only. release_work_accommodation_review_stage re-reads the authoritative Cosmos grades and picks the outcome via review_release_outcome_stage: FAILED_KNOCKOUT when the persisted status is already knockout or a reviewer’s grade now trips grading_has_failed_knockout (a provisionally-full-credit required question scored 0), otherwise CALL_COMPLETED. It transitions under the constrained StageActionProfile.WORK_ACCOMMODATION_REVIEW_RELEASE, which preserves stage history / CAS / activity and fires the matching AI_INTERVIEW_PASSED / AI_INTERVIEW_FAILED ATS move but does not replay results posting, notifications, tasks, scheduling, or billing. A configured ATS integration that cannot be created raises TerminalOutcomeEvaluationError and retains the hold for recovery rather than releasing the Tenzo stage without its ATS move. That ATS resolution lives in application_stage/terminal_outcome_ats_resolution.py, shared with the regrade outcome reconcile below so both restricted terminal moves resolve the client and the pass/fail verdict identically. The release never moves an application that already left review. Resolution is a no-op unless the CCI is still on PENDING_ACCOMMODATION_REVIEW: an overlay that never committed leaves the application on its ordinary terminal stage, which is a finished outcome rather than a state to repair. The ATS side is checked the same way, inside move_interview_outcome_for_review_release and against the application it is about to move: review_release_stage_presence compares that application’s current stage to the stage Tenzo itself last left it on. That is exactly ONE of two target sets — never their union — both read from org config independently of the routing feature flag and of the call’s completion rate:

• the review parking targets (pending_accommodation_review_stage / ..._workflow_step_id plus any stored PENDING_ACCOMMODATION_REVIEW routing rule) when the org configures them, otherwise
• the interview pass targets (ai_interview_pass_stage and its workflow step, plus any stored AI_INTERVIEW_PASSED routing rule).

The second set covers the common configuration: most orgs map no parking stage at all, so the overlay’s ATS move is a no-op and the application is still sitting on the pass stage the completing transition pushed. Without it, every release replayed that outcome move hours later and dragged applicants back out of stages recruiters had moved them to (TEN-809). The fail targets are deliberately in neither set. A recruiter can move someone to the fail stage on purpose, so accepting it as “where Tenzo left them” would let a reviewed pass undo that rejection; and a held application was never pushed there, because the overlay only forms over a completion whose pass evaluation was not a definite fail (should_overlay_work_accommodation_review requires review_could_change_outcome). Unioning the two sets is likewise wrong for a parked org: it would accept an outcome stage a recruiter chose. Targets are split into stages and workflow steps (StageTargetSet). A Workday outcome configured only by workflow-step reference can never compare equal to a fetched application’s stage, because SOAP moves by step even when Kombo exposes no stage that maps to it, so when nothing comparable is configured the check stands down and the move proceeds rather than reporting a recruiter move that did not happen. If the application has left the expected stage the move is skipped without failing — a recruiter’s stage choice wins, and the Tenzo overlay still resolves. If the current stage cannot be read (UNKNOWN — for example Innova’s live VRA read failing) the move fails closed and the hold is retained for a retry, since an unreadable stage cannot distinguish an application Tenzo placed from one already moved. The release comments only when it changed the ATS. The orchestrator’s stage comment is suppressed for WORK_ACCOMMODATION_REVIEW_RELEASE unless the reviewed-outcome move returned MOVED (_should_post_stage_comment / context.reviewed_outcome_ats_move_applied). The terminal stage the release returns to was already entered — and already commented on — before the overlay, so a release that confirms that outcome would write a duplicate note. A release that unparks an application, or that applies a verdict the reviewer flipped, does change what the org sees and keeps its comment.

Regrade outcome reconcile. Changing a knockout question and regrading re-derives the call’s terminal verdict, and the application stage follows it via StageActionProfile.REGRADE_OUTCOME_RECONCILE. It moves only an application still on the graded terminal stage (CALL_COMPLETED / FAILED_KNOCKOUT) that this call itself produced, so a bulk regrade cannot resurrect dispositioned or opted-out candidates. Applications under work-accommodation review are left to the release path above. Completeness is handled asymmetrically, because the two persisted statuses carry different evidence about it. A persisted COMPLETED already established that the candidate reached the scripted outro, so only the knockout dimension is re-decided; re-running completeness against the new question set would let a script edit retroactively demote a finished interview. A persisted FAILED_KNOCKOUT establishes nothing — determine_final_status returns it before the outro check — so when a regrade clears the knockout, completeness is re-established via resolve_graded_terminal_status. If it does not hold the call is INCOMPLETE, which has no application stage to move to, and the persisted verdict is left untouched. The profile fires the same AI_INTERVIEW_PASSED / AI_INTERVIEW_FAILED move, but as a post-commit action rather than a critical one. Critical actions run before the stage CAS, and this reconcile is driven once from an HTTP request with nothing to retry it, so a pre-CAS move that then lost the CAS would leave the ATS permanently ahead of Tenzo. Post-commit means the ATS moves only if the stage it reflects was actually written; a failing move leaves the stage correction standing but is reported as a failed reconcile rather than a clean move, so a Tenzo stage that is ahead of the ATS is visible, and result_edited_since_ats_push keeps the manual re-push available. A question the candidate was never asked — the row a regrade back-fills when it adds a question — can never fail a knockout or move the pass/fail score. The marker is structural (GradeResult.never_asked / CosmosRequirementGrade.never_asked), written only by the back-fill, because the same placeholder shape is also used when grading cannot resolve a requirement. Outcome-affecting unresolved placeholders abort post-call and regrade processing instead of being persisted as candidate outcomes; non-required INFO GRADE_ONLY failures may remain explicitly marked placeholders. The reviewer grade-edit endpoint accepts free-form answer text, so a text match would let a typed “Not asked” clear a genuine knockout. Rows persisted before the marker existed are recognised by the full shape the back-fill stamped (sentinel answer, no-evidence transcript index, sentinel rationale), which the edit endpoint cannot reproduce. grading_utils.is_failed_knockout_grade is the single definition of “this zero records a real failure” — grading_has_failed_knockout delegates to it — and the same exclusion reaches the weighted average, both all-binary lifts, the bucket rescale and the completion rate, so the knockout verdict and the persisted score cannot disagree.

​

How Routing Is Evaluated

​

Stage-move path — _handle_stage_movement_for_target

RoutingEvent.DO_NOT_CONTACT still exists as an inert enum member so previously persisted stage_routing_rules blobs continue to parse. Nothing fires it, no handler or flat config field backs it, and it is not offered in the admin routing UI. Opt-outs use CONSENT_REVOKED.

_handle_stage_movement_for_target(ats_application_id, flat_stage, flat_wf_step, label,
                                   routing_event=..., completion_rate=...)
    │
    ├─ if routing_event is not None:
    │     routed = await _move_application_for_routing_match(...)
    │     if routed: return   ← flat-field path is suppressed
    │
    └─ flat-field path: load app/job, move to flat_stage / flat_wf_step

​

Disposition path — _apply_disposition_routing_outcome

handle_*_application(application_id, completion_rate=...)
    │
    ├─ if await _apply_disposition_routing_outcome(...):
    │     return   ← legacy flat-field path skipped
    │
    └─ legacy disposition or stage move from flat config

​

_move_application_for_routing_match Decision Tree

routing_enabled = await _is_ats_stage_routing_rules_enabled()
match = resolve_routing_match(org_config, event, completion_rate, routing_enabled)

if not routing_enabled or match is None:
    return False   ← caller falls through to flat-field path

# routing_enabled=True and match is resolved
target_stage = match.action.stage
target_step  = flat_workflow_step (if non-empty) else match.action.workflow_step_id

if not has_configured_transition_target(target_stage, target_step):
    log WARNING "No ATS routing target configured"
    return True   ← flat-field path is SUPPRESSED (candidate NOT moved)

app = await get_application_by_application_id(ats_application_id)
if not app:
    log ERROR
    return True   ← flat-field path suppressed

job = await get_job_by_job_id(app.job_id)
if not job:
    log ERROR
    return True   ← flat-field path suppressed

await move_application_for_org_transition_config(app, job, target_stage, target_step)
return True       ← flat-field path suppressed

​

Routing Rule Resolution (resolve_routing_match)

resolve_routing_match(accessor, event, completion_rate, routing_rules_enabled)
    │
    ├─ routing_rules_enabled=False → return None
    │
    ├─ get_effective_stage_routing_rules(accessor)
    │     ├─ synthesize defaults from legacy flat fields (stage + disposition)
    │     ├─ accessor.stage_routing_rules is set and non-empty → merge persisted rule sets
    │     │     (persisted events win; synthesized fills gaps for other events)
    │     └─ otherwise → use synthesized rules only
    │
    ├─ rules_value.get_rule_set(event)  → None if event has no rule set
    │     └─ None → return None (caller: _move_application_for_routing_match returns False)
    │
    └─ evaluate_rule_set(rule_set, context)
          ├─ sort rules by priority (ascending)
          ├─ for each rule: evaluate ALL conditions (AND logic)
          │     condition: metric=completion_percentage, op in {gte,gt,lte,lt,eq}, value
          │     if completion_percentage is None → condition NEVER matches
          │
          ├─ first matching rule → RoutingMatchResult(used_default=False, ...)
          └─ no rule matched → default_rule → RoutingMatchResult(used_default=True, ...)

​

Default Rule Synthesis from Flat Config

outreach_stage = "Outreach In Progress"
→ EventRoutingRuleSet(
      event=OUTREACH,
      default_rule=RoutingDefaultRule(action=RoutingAction(stage="Outreach In Progress")),
      rules=[]
  )

​

Special Case: CALL_LIMIT_EXHAUSTED

CALL_LIMIT_EXHAUSTED:
  default_rule.action.stage = call_limit_no_interview_stage  (or not_completed if former is None)
  rules = [
    RoutingRule(conditions=[completion_percentage > 0], action.stage = call_limit_not_completed_stage)
  ]

• completion_rate=None → no conditional fires → default rule → no_interview_stage
• completion_rate=0.0 → percentage=0 → condition > 0 is false → default → no_interview_stage
• completion_rate=0.5 → percentage=50 → condition > 0 is true → not_completed_stage

​

Completion Rate Flow for Call-Limit Events

completion_rate=completion_rate if completion_rate is not None else 0.0

​

Terminal / Fallback Behaviour

1. OUTREACH: Stage set when Tenzo begins contact. If unconfigured, no movement.
2. OUTREACH_PAUSED: Set when outreach is temporarily paused.
3. CALL_LIMIT_NO_INTERVIEW / CALL_LIMIT_EXHAUSTED: Terminal states after max attempts.
4. CALL_LIMIT_REACHED (legacy): Used by orgs that haven’t migrated to the split events.

The legacy call_limit_reached_* fields do not serve as a fallback for the new split events. An org migrating to split call-limit stages must configure call_limit_no_interview_* and/or call_limit_not_completed_* explicitly.

​

Known Failure Modes and Risks

​

1. Misconfigured Routing Target → Candidate Stranded

​

2. No Rule Set for Event → Falls Through to Flat Field

​

3. Legacy CALL_LIMIT_REACHED vs Split Events

​

4. Missing ATS Application or Job After Routing Resolves

​

5. Empty Kombo current_stage Is Unknown, Not Outreach-Ineligible

​

Code Locations

​

Tests