Use these instructions when solving PeopleOps Console tasks that involve leave verification, payroll readiness, recruitment reconciliation, case folder review, or cross-module lifecycle controls.
Base Setup
The task environment provides a base URL in the form
<TASK_ENV_BASE_URL>. Construct all API calls by appending the endpoint
paths listed below to that base. Credentials:
ops.lead@peopleops.local
PeopleOps#2026
The API is read-only for all GET endpoints listed under Allowed Endpoints.
There is a POST /api/cases/{case_id}/comments endpoint for adding comments
but it is rarely needed. Do not call /api/judge.
Core Business Policies
These four policies control every workflow. Read them from
/api/policies/{policy_id} when the task crosses a policy boundary, or rely
on the rules summarized here when the policy text is not critical to the
current subtask.
| Policy ID | Domain | Core Rule |
|---|---|---|
| LEAVE-SRC-001 | Leave precedence | The latest Approved or Submitted leave assignment for the period controls. Draft, voided, and obsolete records are excluded even when profile summaries conflict. |
| PAY-SRC-001 | Payroll assignment | Use the current Submitted salary assignment. Draft planning assignments do not affect payroll readiness or accrual checks. Recruiting payroll handoff is created only after a selected candidate has an accepted offer; the handoff must be Submitted. |
| HR-POL-014 | Remote work | Remote work exceptions require executive approval, time limits, tax equalization, VPN-only access, quarterly compliance review, appeal instructions, and acknowledgement deadline in the formal notice. |
| POL-DOCS-2026 | Folder checklist | A folder is not ready unless all required files and required tags shown in the folder checklist are present. |
API Endpoints and Usage
Discovery
Start with GET /api/summary and GET /api/manifest to orient yourself.
Reference Data (index endpoints)
| Endpoint | Returns |
|---|---|
| GET /api/employees | All employee profiles with status, leave_balance, department, salary_band |
| GET /api/cases | All cases with status, owner, policy_refs, summary |
| GET /api/policies | All policy documents with sections |
| GET /api/payroll-ledgers | Mixed ledger: leave assignments, salary assignments, accrual records, HRMS ledger entries |
| GET /api/recruitment | Recruitment openings with candidates, offers, cost ledger, notice packets |
| GET /api/documents | Document folders with files, required_files, required_tags, tags, ready flag |
| GET /api/messages | Formal notices with quality, defects, status |
| GET /api/audit | Audit events with actor, event type, detail |
| GET /api/notifications | Notifications (supplementary) |
Detail Endpoints
GET /api/cases/{case_id}-- case detail including approvals, attachments, audit_events (case-scoped), commentsGET /api/policies/{policy_id}-- single policy detailGET /api/audit/{audit_id}-- single audit event detailGET /api/attachments/{attachment_id}-- attachment content (e.g. folder checklist text)
Important Structural Notes
Payroll-ledgers is a mixed endpoint. Every record has a record_type field.
Filter on record_type to isolate the relevant slice:
"Leave assignment"--ledger_idis the leave assignment ID,statusisApproved,Superseded,Draft, etc."Salary assignment"--ledger_idis the payroll assignment ID, containsbase_salary,accrual_batch_id- Other record types (
People Ops adjustment,Payroll worksheet,HRMS leave ledger) are noise records for most tasks.
Recruitment returns an array of openings. Each opening contains:
candidates[]-- candidate list withcommittee_decision(Selected,Waitlisted,Rejected)offer_register[]-- offers withstatus(accepted,draft,withdrawn)cost_ledger[]-- cost line items withamountnotice_packets[]-- notice status per candidate withnotice_type,required_action,defectspayroll_precheck_records[]-- draft precheck records (excluded from handoff)
Documents returns folders. Key fields: files[] (present), required_files[]
(expected), tags[] (present), required_tags[] (expected), ready (boolean).
Messages returns formal notices. Key fields: quality (valid / defective),
defects[] (e.g. missing_appeal_instructions, missing_ack_deadline,
missing_waitlist_status, missing_correct_policy).
Workflow Decision Tree
Identify the task type from the prompt and follow the corresponding workflow.
1. Leave Verification (leave policy, balance, assignment)
Goal: Determine the effective leave policy, annual days, and assignment ID for an employee. Apply source precedence.
Procedure:
Call
GET /api/employeesand find the target employee by ID or name. Note the profileleave_balance_daysand department -- these are reference values, not authoritative.Call
GET /api/payroll-ledgersand filter forrecord_type: "Leave assignment",employee_id: <target>. Sort byupdated_atdescending.Apply the LEAVE-SRC-001 rule:
- Select the record with the latest
updated_atwhosestatusisApprovedorSubmitted. - Exclude all records with
statusofDraft,Voided, orSuperseded. - The selected record's
policy_nameis the effective leave policy. - The selected record's
approved_leave_daysis the annual days. - The selected record's
ledger_idis the assignment ID.
- Select the record with the latest
Collect excluded IDs: every record for the target employee whose
statusis not the selected authoritative status (i.e.Superseded,Draft,Voided).Leave source is always
leave_assignment_historywhen you used the ledger to find the authoritative record.Leave precedence source is
approved_assignment_current_periodwhen an Approved/Submitted assignment was found.Cross-check against the task's case (if any). Call
GET /api/cases/{case_id}and examineaudit_events. If the task mentions a profile mismatch or stale profile, identify the audit event confirming the stale profile. That audit event is the supporting evidence.If the task also asks about payroll for the same employee, follow the payroll workflow below for that employee.
Decision rule: When the ledger assignment's policy or days differ from the profile, the ledger assignment controls. The profile is stale.
2. Payroll Assignment Verification
Goal: Verify the submitted payroll assignment, exclude draft records, and determine accrual readiness.
Procedure:
Call
GET /api/payroll-ledgersand filter forrecord_type: "Salary assignment",employee_id: <target>.Apply the PAY-SRC-001 rule:
- Select the record with
status: "Submitted". - Exclude all records with
status: "Draft"(orSuperseded). - The selected record's
ledger_idis the payroll assignment ID. - The selected record's
base_salaryis the base salary. - If the record has an
accrual_batch_id, note it.
- Select the record with
Accrual readiness: if the submitted record references an
accrual_batch_idand the task asks about accrual, check that the batch ID exists and the record is submitted. The accrual is ready when the submitted assignment is clean.If a case is associated, call
GET /api/cases/{case_id}and examineaudit_eventsfor payroll-related events. Use the audit event that confirms the submitted assignment controls.payroll_source_statusissubmitted.draft_exclusion_ruleisexclude_draft_assignment.audit_scopeispayroll_assignment_readiness.control_result:ready_with_monitoringwhen the submitted assignment is found and no blockers exist.approve_closeoutwhen the task is an onboarding closeout and both leave and payroll are clean.
3. Case Folder and Notice Review
Goal: Review a case's folder readiness and formal notice quality.
Procedure:
Call
GET /api/cases/{case_id}to get case detail, approvals, attachments, and case-scoped audit events.Evidence order:
approval_history_folder_notice_audit- First read approvals to understand the decision and authority.
- Then check the folder (documents API).
- Then inspect the formal notice (messages API or case attachments).
- Then corroborate with audit events.
Folder check: Use the case's
policy_refsand attachment checklist. CallGET /api/documentsand locate the folder for this case (match by employee or case context). Verify:filescontains allrequired_files. Missing files are listed inmissing_files.tagscontains allrequired_tags. If a required tag is absent,required_tag_presentis false.
Notice check: Call
GET /api/messagesand locate the message for this case (match bycase_id). Determine:quality:validordefectivedefects[]: list of defect codes found- If the message quality is
defective,notice_qualityisdefective.
Decision:
- If folder is not ready or notice is defective:
final_decision:approved_with_conditions(if approval exists) orheldapproval_closeout_gate:approval_not_sufficient_when_folder_or_notice_defectivecloseout_blockers: list the applicable blockers (missing_required_files,defective_formal_notice,missing_required_tags)next_action:block_close_and_reissue_noticewhen notice is defective;open_records_remediationwhen folder is defectivefinal_control_result:hold_for_folder_and_notice_defects
- If both folder and notice are clean:
approval_closeout_gate:approval_sufficient_when_records_cleanfinal_control_result:approve_closeoutorready_with_monitoring
- If folder is not ready or notice is defective:
Audit events: Use the audit events from the case detail or
/api/audit. The primaryaudit_event_idis the one most directly related to the document/notice findings. Supporting events are those in the same scope. Excluded events are those outside the document/notice scope (e.g. payroll or leave events when the task scope is document/notice).Audit scope for case folder/notice tasks:
document_notice_findings_only.Notice evidence source:
notice_packet_inspectionwhen you read the messages endpoint;message_notice_inspectionwhen the notice evidence is only in messages.
4. Recruitment Reconciliation
Goal: Reconcile a recruitment opening's candidate outcomes, offer, costs, notice follow-ups, and payroll handoff.
Procedure:
Call
GET /api/recruitmentand locate the target opening byopening_id.Candidate outcomes from the
candidates[]array:committee_decision: "Selected"->selected_candidatecommittee_decision: "Waitlisted"->waitlisted_candidatescommittee_decision: "Rejected"->rejected_candidatescandidate_status_source:interview_feedback_and_offercandidate_outcome_control:committee_decision_with_offer_confirmation
Offer details from
offer_register[]:- Match the selected candidate to their offer.
offer_idandoffer_base_salaryfrom the matched offer.selected_offer_status:accepted,draft,withdrawn, ornone(when no offer exists for the selected candidate).offer_exclusion_reason_for_waitlisted:no_accepted_status_or_offer
Recruitment cost: Sum all
amountvalues incost_ledger[].cost_source:recruitment_cost_ledger.Notice follow-up from
notice_packets[]:- For waitlisted candidates: check if a waitlist notice is required.
If
statusisnot_sent, the candidate needssend_waitlist_notice. Ifstatusisdraft_reissue_required, usereissue_waitlist_notice_not_rejection.waitlisted_followup_actionmaps to the required action. - For rejected candidates: check if a rejection notice is required.
If
statusisnot_sent, usesend_rejection_notice.rejected_followup_actionmaps to the required action. notice_followup_required: list of candidate IDs needing any notice follow-up.notice_quality_source:notice_packet_inspection
- For waitlisted candidates: check if a waitlist notice is required.
If
Payroll handoff:
- Only proceed if the selected candidate has an
acceptedoffer. payroll_handoff_gate:accepted_offer_onlypayroll_assignment_status_required:submitted_after_acceptancedraft_payroll_allowed:falseonboarding_handoff:create_payroll_precheckhandoff_control_result:submitted_handoff_required_after_acceptance
- Only proceed if the selected candidate has an
Exclude
payroll_precheck_records[]from the handoff gate decision -- they are draft placeholders.
5. Leave Precedence Dispute (profile vs assignment)
Goal: When the profile summary conflicts with the leave ledger, determine which source is authoritative.
Procedure:
Follow the Leave Verification workflow (Section 1) to find the authoritative assignment from the ledger.
Compare the profile's
leave_balance_daysand department context against the ledger assignment'spolicy_nameandapproved_leave_days.If they differ, the ledger assignment controls per LEAVE-SRC-001.
precedence_source:approved_assignment_over_profileleave_precedence_source:approved_assignment_current_periodprofile_policy_ignored:trueaudit_result:profile_summary_stalenext_action:update_employee_summary
Audit event separation: When the task asks for audit events:
supporting_audit_event_ids: audit events that confirm the leave precedence decision (e.g.leave.profile_mismatchevents).excluded_audit_event_ids: audit events that are about document folders or notice quality -- they are adjacent but outside the leave scope.audit_scope:leave_source_precedence_only
The audit event confirming the stale profile is the primary
audit_event_id.
6. Onboarding Closeout (combined leave + payroll)
Goal: Combined workflow -- verify both leave and payroll for an onboarding employee, then determine the closeout action.
Procedure:
Run the Leave Verification workflow (Section 1) for the target employee.
Run the Payroll Assignment Verification workflow (Section 2) for the same employee.
Closeout decision:
- If both leave and payroll are clean (no blockers):
closeout_action:approve_onboarding_closeapproval_closeout_gate:approval_sufficient_when_records_cleanfinal_control_result:approve_closeout
- If leave has blocked records or payroll has issues:
closeout_action:block_close_and_reissue_noticeoropen_records_remediationdepending on the nature of the issue.
- If both leave and payroll are clean (no blockers):
Status Filtering Rules
These rules apply across all workflows:
| Record Type | Authoritative Statuses | Excluded Statuses |
|---|---|---|
| Leave assignment | Approved, Submitted |
Superseded, Draft, Voided |
| Salary assignment | Submitted |
Draft, Superseded |
| Payroll precheck | Submitted |
Draft |
| Offer | accepted |
draft, withdrawn |
Always exclude draft records unless the task explicitly instructs otherwise. Superseded records are historically prior and no longer authoritative.
Audit Scope Separation
Audit events serve different business scopes. When a task asks for audit events, identify which scope applies and include only events in that scope.
| Audit Event Type | Scope |
|---|---|
leave.profile_mismatch |
leave_source_precedence_only |
payroll.ready, payroll.draft_excluded |
payroll_assignment_readiness |
notice.defect, case.close_blocked, folder.tag_missing |
document_notice_findings_only |
cross_module.escalation_package |
Cross-module -- read its detail for related event IDs |
When the task scope is leave_source_precedence_only, exclude
document/notice events (like folder.tag_missing). When the task scope is
document_notice_findings_only, exclude leave and payroll events.
Evidence Order
For each task type, gather evidence in this order:
- Leave/payroll tasks: employee profile -> payroll-ledgers -> policies -> case detail -> audit events
- Case folder/notice tasks: case detail (approvals) -> documents folder -> messages (notice) -> audit events
- Recruitment tasks: recruitment opening -> offer register -> cost ledger -> notice packets -> payroll precheck records
Always consult the relevant policy document (/api/policies/{policy_id}) when
the task references a policy or when you need to validate a business rule.
The policy text is authoritative for edge cases.
Output Format
Every task provides an answer_template.json in
input/payloads/answer_template.json. Read this template first -- it defines
the exact JSON shape, field types, and allowed enum values for the response.
Use only the normalized enum values listed in the template. Do not use
free-text explanations for enum fields.
Return the final answer as a single JSON object matching the template exactly. Do not include markdown fences or explanatory text unless the task prompt permits it.
Quick Reference: Normalized Enum Values
These are the common enum values used across tasks. Always defer to the task's answer template for the exact set.
Leave source: leave_assignment_history, employee_profile_summary,
case_summary_only
Leave precedence: approved_assignment_current_period,
profile_summary_current_period, case_summary_only
Payroll source status: submitted, draft, superseded
Draft exclusion: exclude_draft_assignment, draft_allowed,
exclude_superseded_only
Audit scope: leave_source_precedence_only, document_notice_findings_only,
payroll_assignment_readiness
Closeout action: approve_onboarding_close, block_close_and_reissue_notice,
open_records_remediation
Approval gate: approval_sufficient_when_records_clean,
approval_not_sufficient_when_folder_or_notice_defective
Final control result: approve_closeout, hold_for_folder_and_notice_defects,
ready_with_monitoring
Notice quality: valid, defective
Notice defects: missing_ack_deadline, missing_appeal_instructions,
missing_waitlist_status, missing_correct_policy
Candidate outcome control: committee_decision_with_offer_confirmation,
message_status_only, case_summary_only
Offer status: accepted, draft, withdrawn, none
Notice evidence source: notice_packet_inspection, message_notice_inspection,
case_summary_only
Payroll handoff gate: accepted_offer_only,
accepted_offer_and_submitted_assignment, all_interviewed_candidates
Handoff control result: submitted_handoff_required_after_acceptance,
submitted_handoff_required, no_handoff_required
Next action (leave): update_employee_summary, open_records_remediation,
no_action
Precedence source: approved_assignment_over_profile,
employee_profile_summary, case_summary_only
Audit result: profile_summary_stale, ready_with_monitoring, block_close
Evidence source order: approval_history_folder_notice_audit,
folder_notice_audit, audit_only
Folder tag action: no_tag_action, add_required_tag
Escalation action: open_records_remediation,
block_close_and_reissue_notice, no_action
Records remediation owner: Records, People Ops Compliance, Payroll QA
Notice remediation action: reissue_defective_notices, no_notice_action,
send_new_offer_notice
Waitlisted followup action: send_waitlist_notice,
reissue_waitlist_notice_not_rejection, no_action
Rejected followup action: send_rejection_notice, no_action,
reissue_rejection_notice
Onboarding handoff: create_payroll_precheck,
create_submitted_assignment_after_acceptance, no_payroll_handoff
Candidate status source: interview_feedback_and_offer, case_summary_only,
message_only
Cost source: recruitment_cost_ledger, case_summary_only
Payroll assignment status required: submitted_after_acceptance,
submitted, draft_allowed
Offer exclusion reason: no_accepted_status_or_offer,
waitlisted_not_selected, already_rejected