Add AICL example: 38_hr_management.aicl

data/aicl/examples/38_hr_management.aicl

@@ -0,0 +1,367 @@
+# AICL Example: HR Management System
+# End-to-end human resources management system covering employee lifecycle, payroll processing, benefits administration, performance management, and recruitment with compliance automation
+
+Goal: Provide a comprehensive human resources management platform that automates the entire employee lifecycle from recruitment through offboarding, ensures payroll accuracy across jurisdictions, streamlines benefits enrollment, enables continuous performance management, and maintains regulatory compliance with labor laws and data privacy regulations
+
+Constraint: All employee personal data must be encrypted and access-logged with role-based restrictions enforcing least-privilege principles
+Constraint: Payroll calculations must comply with federal, state, and local tax regulations with automated table updates
+Constraint: Performance evaluations must follow structured rubrics preventing unauthorized modification after submission
+Constraint: Recruitment processes must enforce equal opportunity compliance with bias detection on job postings and screening criteria
+Constraint: Benefits enrollment must honor plan eligibility rules, coverage periods, and qualifying life event windows
+
+Risk: Payroll miscalculation due to incorrect tax jurisdiction assignment or outdated rate tables
+Recovery: Halt affected payroll run immediately; revert to last validated tax configuration; recalculate using corrected tables; generate adjustment entries with full audit trail; notify affected employees and finance team
+
+Risk: Unauthorized access to employee sensitive data including salary and medical information
+Recovery: Revoke compromised access credentials; audit all recent data access logs; notify affected employees per breach notification requirements; enforce mandatory access review; implement additional authentication layer
+
+Risk: Recruitment bias in automated screening causing discriminatory candidate filtering
+Recovery: Disable automated screening rule immediately; revert to manual review process; audit screening criteria for protected class correlations; re-evaluate all affected candidates; report findings to compliance and legal
+
+Risk: Benefits enrollment processing failure during open enrollment period
+Recovery: Extend enrollment deadline automatically; switch to manual processing queue; preserve all submitted elections; notify HR and benefits team; engage carrier liaison for deadline accommodation; log incident for post-mortem
+
+Risk: Performance review data loss before manager submission
+Recovery: Enable auto-save with 30-second intervals; restore from last autosave checkpoint; maintain versioned drafts; prevent form timeout during active editing; notify user of recovery action taken
+
+Risk: Employee offboarding incomplete leaving active access to systems and data
+Recovery: Trigger comprehensive offboarding checklist on termination date; automatically revoke all system access within 1 hour; verify deprovisioning completion; escalate incomplete items to IT security; generate compliance attestation report
+
+Layer: EmployeeLifecycle
+    SubLayer: Onboarding
+    SubLayer: EmployeeRecords
+    SubLayer: Transfers
+    SubLayer: Offboarding
+
+Layer: Payroll
+    SubLayer: TimeTracking
+    SubLayer: TaxCalculation
+    SubLayer: DeductionEngine
+    SubLayer: PaymentProcessing
+
+Layer: Benefits
+    SubLayer: PlanManagement
+    SubLayer: EnrollmentEngine
+    SubLayer: ClaimsCoordination
+    SubLayer: COBRASystems
+
+Layer: Performance
+    SubLayer: GoalSetting
+    SubLayer: ReviewCycles
+    SubLayer: FeedbackEngine
+    SubLayer: SuccessionPlanning
+
+Layer: Recruitment
+    SubLayer: RequisitionManagement
+    SubLayer: ApplicantTracking
+    SubLayer: InterviewScheduling
+    SubLayer: OfferManagement
+
+Validation: Payroll gross-to-net calculations must pass tolerance check within 0.01 percent of expected values
+Validation: Performance review submissions must include self-assessment, manager assessment, and at least one peer review
+Validation: Benefits enrollment selections must not exceed plan maximums or create coverage gaps
+Validation: Job requisitions must include approved headcount budget and validated department code
+Validation: Employee offboarding must complete all checklist items before final paycheck release
+Validation: Time entries must fall within authorized schedule windows and comply with overtime regulations
+
+Entity EmployeeRecord
+    employeeId: string
+    firstName: string
+    lastName: string
+    dateOfBirth: datetime
+    ssnEncrypted: bytes
+    email: string
+    phone: string
+    address: dict
+    department: string
+    jobGrade: string
+    hireDate: datetime
+    employmentStatus: string
+    managerId: string
+    workLocation: string
+
+Entity PayrollRun
+    payrollRunId: string
+    payPeriodStart: datetime
+    payPeriodEnd: datetime
+    runDate: datetime
+    status: string
+    totalGross: float
+    totalTaxes: float
+    totalDeductions: float
+    totalNet: float
+    employeeCount: integer
+    jurisdiction: string
+    processingMode: string
+
+Entity BenefitsEnrollment
+    enrollmentId: string
+    employeeId: string
+    planYear: string
+    medicalPlan: string
+    dentalPlan: string
+    visionPlan: string
+    lifeInsurance: string
+    retirementPlan: string
+    fsaContribution: float
+    hsaContribution: float
+    dependents: list
+    enrollmentDate: datetime
+    qualifyingEvent: string
+
+Entity PerformanceReview
+    reviewId: string
+    employeeId: string
+    reviewerId: string
+    reviewCycle: string
+    selfAssessment: dict
+    managerAssessment: dict
+    peerReviews: list
+    goalProgress: list
+    overallRating: float
+    competencyScores: dict
+    developmentPlan: dict
+    status: string
+    submittedDate: datetime
+
+Entity JobRequisition
+    requisitionId: string
+    jobTitle: string
+    department: string
+    hiringManager: string
+    headcountBudget: float
+    salaryRange: dict
+    employmentType: string
+    location: string
+    requiredSkills: list
+    preferredSkills: list
+    postingDate: datetime
+    targetFillDate: datetime
+    approvalStatus: string
+    diversityRequirements: dict
+
+Entity TimeEntry
+    entryId: string
+    employeeId: string
+    date: datetime
+    hours: float
+    timeType: string
+    project: string
+    approvalStatus: string
+    approvedBy: string
+    overtimeHours: float
+    breakDuration: integer
+    location: string
+
+Behavior ProcessPayrollRun
+    Input: payPeriodStart: datetime, payPeriodEnd: datetime, jurisdiction: string
+    Output: payrollRunResult: PayrollRun
+    Action: Load active employee roster for period; aggregate approved time entries; calculate gross compensation including overtime; apply federal state and local tax withholdings; process benefit deductions; calculate employer contributions; validate net pay tolerances; generate payment file; create payroll journal entries; emit payroll completed event
+
+Behavior EnrollBenefits
+    Input: employeeId: string, planYear: string, selections: dict, qualifyingEvent: string
+    Output: enrollmentConfirmation: BenefitsEnrollment
+    Action: Verify employee eligibility for each selected plan; validate enrollment window or qualifying event; check dependent eligibility; compute employee and employer cost shares; validate total contribution limits; persist enrollment; transmit to benefits carrier; emit enrollment confirmed event; update payroll deduction schedule
+
+Behavior SubmitPerformanceReview
+    Input: reviewId: string, assessmentData: dict, reviewerType: string
+    Output: submissionConfirmation: dict
+    Action: Validate review period is open; check reviewer authorization; enforce required assessment sections; compute overall rating from competency scores; detect and flag calibration outliers; persist submission; check if all required reviews are complete; emit review submitted event; trigger next step in review workflow
+
+Behavior ProcessOffboarding
+    Input: employeeId: string, terminationDate: datetime, reason: string
+    Output: offboardingResult: dict
+    Action: Generate offboarding checklist; schedule exit interview; initiate benefits continuation processing; calculate final paycheck including PTO payout; trigger system access revocation; transfer knowledge responsibilities; archive employee records per retention policy; emit offboarding initiated event; generate compliance attestation
+
+Behavior CreateJobRequisition
+    Input: jobTitle: string, department: string, hiringManager: string, salaryRange: dict, requirements: dict
+    Output: requisition: JobRequisition
+    Action: Validate headcount budget availability; check department approval chain; scan job description for biased language; validate required fields; apply approval workflow based on grade and salary range; persist requisition; emit requisition created event; initiate recruiting workflow; update workforce planning dashboard
+
+Behavior ApproveTimeEntries
+    Input: managerId: string, entryIds: list, approvalDecision: string, notes: string
+    Output: approvalResult: dict
+    Action: Verify manager authorization for submitted employees; validate hours against schedule policies; check overtime compliance; apply approval or rejection; update entry status; recalculate overtime if applicable; emit time entry approved event; flag exceptions for HR review; update time and attendance records
+
+Condition:
+    When employee.employmentStatus changes to "terminated" AND employee has active benefits enrollment
+    Then initiate COBRA notification process within 14 days; generate benefits continuation election form; set coverage end date per plan rules; notify benefits carrier; update payroll deduction termination schedule
+
+Condition:
+    When timeEntry.overtimeHours exceeds 20 in a single workweek
+    Then flag for manager and HR review; verify compliance with labor regulations; calculate premium pay rate adjustments; alert workforce management; generate overtime exception report
+
+Condition:
+    When performanceReview.overallRating deviates more than 1.5 standard deviations from team average
+    Then trigger calibration review workflow; notify HR business partner; require additional justification from reviewer; hold review in pending calibration status; log deviation for trend analysis
+
+Condition:
+    When benefitsEnrollment.fsContribution exceeds annual IRS limit
+    Then reject contribution election; notify employee and HR; apply maximum allowable contribution; generate limit notification; adjust payroll deduction accordingly
+
+Condition:
+    When jobRequisition job description contains potential bias indicators per NLP analysis
+    Then flag posting for diversity and inclusion review; suggest alternative neutral language; prevent publishing until review cleared; log bias detection results; update screening criteria audit trail
+
+Event:
+    On PayrollRunCompleted
+    Action: Submit payment file to banking system; post payroll journal entries to finance; update employee year-to-date accumulations; generate payslip notifications; sync benefits deductions with carriers; archive payroll register
+
+Event:
+    On BenefitsEnrollmentConfirmed
+    Action: Update payroll deduction configuration; transmit enrollment to carrier; generate employee confirmation statement; update benefits dashboard; trigger ID card issuance if applicable; log enrollment for compliance reporting
+
+Event:
+    On PerformanceReviewCycleClosed
+    Action: Calculate compensation adjustment recommendations; generate talent review summaries; update succession planning data; trigger development plan creation; publish aggregate analytics to leadership; archive review documents
+
+Event:
+    On EmployeeOffboardingComplete
+    Action: Verify all access revoked; generate final compliance attestation; transfer records to archive; update headcount reporting; process alumni network enrollment; close outstanding HR tickets; release final paycheck
+
+Event:
+    On JobRequisitionApproved
+    Action: Publish to internal and external job boards; activate applicant tracking workflow; schedule recruiter briefing; configure screening automation; set diversity sourcing targets; notify hiring manager of posting
+
+Parallel:
+    - Payroll gross-to-net calculation engine per jurisdiction
+    - Benefits enrollment validation and carrier transmission
+    - Performance review calibration analytics
+    - Recruitment screening pipeline execution
+    - Employee data privacy compliance monitoring
+
+Optimize: Employee experience and payroll processing accuracy
+    Priority: Payroll accuracy and tax compliance over processing speed
+    Priority: Data privacy and access control over analytics convenience
+    Priority: Employee self-service responsiveness over administrative batch efficiency
+    Priority: Recruitment fairness and compliance over time-to-fill metrics
+
+Learn: Employee attrition prediction
+    Goal: Identify flight risk employees 90 days before voluntary departure with 70 percent recall
+    Adapt: Retention intervention triggers and timing
+    Based: Engagement survey trends, compensation market positioning, tenure patterns, and manager effectiveness scores
+
+Learn: Compensation benchmarking accuracy
+    Goal: Maintain salary recommendations within 5 percent of market median
+    Adapt: Salary range adjustments and offer guidance
+    Based: Market survey data, internal equity analysis, and candidate acceptance rate trends
+
+Learn: Time-to-hire optimization
+    Goal: Reduce average time-to-hire by 30 percent without sacrificing quality of hire
+    Adapt: Interview stage configurations and screening criteria
+    Based: Stage duration analytics, candidate pipeline velocity, and quality-of-hire outcomes
+
+Learn: Benefits utilization efficiency
+    Goal: Optimize plan offerings to maximize employee satisfaction while controlling cost per employee
+    Adapt: Plan recommendation engine and enrollment guidance
+    Based: Claims utilization patterns, employee satisfaction surveys, and cost trend analysis
+
+Security:
+    Encrypt: All employee personally identifiable information including SSN, date of birth, and medical data
+    Encrypt: Salary and compensation data at rest and in transit with field-level encryption
+    Encrypt: Banking details for direct deposit with hardware security module key management
+    Protect: Payroll processing initiation with dual-authorization and segregation of duties
+    Protect: Performance review data with manager-only access and HR oversight audit trail
+    Protect: Recruitment candidate data with anonymization during screening phase
+    Protect: Benefits enrollment and claims data with HIPAA-compliant access controls
+
+Native: python
+{
+from datetime import datetime, date, timedelta
+from decimal import Decimal
+from typing import Dict, List, Optional
+
+class PayrollCalculator:
+    """Multi-jurisdiction payroll calculation engine with tax compliance."""
+
+    def __init__(self, tax_tables: Dict, benefit_rules: Dict):
+        self.tax_tables = tax_tables
+        self.benefit_rules = benefit_rules
+
+    def calculate_gross_to_net(self, employee: Dict, time_entries: List[Dict]) -> Dict:
+        gross = self._calculate_gross(employee, time_entries)
+        taxes = self._calculate_taxes(gross, employee)
+        deductions = self._calculate_deductions(gross, employee)
+        net = gross - taxes["total"] - deductions["total"]
+
+        return {
+            "employee_id": employee["employee_id"],
+            "gross_pay": float(gross),
+            "federal_tax": float(taxes["federal"]),
+            "state_tax": float(taxes["state"]),
+            "local_tax": float(taxes.get("local", Decimal("0"))),
+            "social_security": float(taxes["social_security"]),
+            "medicare": float(taxes["medicare"]),
+            "benefit_deductions": float(deductions["benefits"]),
+            "retirement_deductions": float(deductions["retirement"]),
+            "other_deductions": float(deductions["other"]),
+            "net_pay": float(net),
+            "calculation_timestamp": datetime.utcnow().isoformat()
+        }
+
+    def _calculate_gross(self, employee: Dict, entries: List[Dict]) -> Decimal:
+        regular_hours = sum(e["hours"] for e in entries if e["time_type"] == "regular")
+        overtime_hours = sum(e["hours"] for e in entries if e["time_type"] == "overtime")
+        hourly_rate = Decimal(str(employee["salary"])) / Decimal("2080")
+        return (hourly_rate * Decimal(str(regular_hours)) +
+                hourly_rate * Decimal("1.5") * Decimal(str(overtime_hours)))
+
+    def _calculate_taxes(self, gross: Decimal, employee: Dict) -> Dict:
+        federal = self._federal_withholding(gross, employee)
+        state = self._state_withholding(gross, employee)
+        ss = min(gross * Decimal("0.062"), Decimal("9932"))
+        medicare = gross * Decimal("0.0145")
+        return {
+            "federal": federal, "state": state,
+            "local": Decimal("0"), "social_security": ss,
+            "medicare": medicare,
+            "total": federal + state + Decimal("0") + ss + medicare
+        }
+
+    def _calculate_deductions(self, gross: Decimal, employee: Dict) -> Dict:
+        benefits = Decimal(str(employee.get("benefit_deduction", "0")))
+        retirement = gross * Decimal(str(self.benefit_rules.get("401k_rate", 0.05)))
+        return {
+            "benefits": benefits, "retirement": retirement,
+            "other": Decimal("0"),
+            "total": benefits + retirement
+        }
+
+
+class OffboardingChecklist:
+    """Manages comprehensive employee offboarding with compliance tracking."""
+
+    def __init__(self, system_registry: Dict):
+        self.systems = system_registry
+        self.required_items = [
+            "system_access_revocation", "equipment_return",
+            "knowledge_transfer", "exit_interview",
+            "final_paycheck_calculation", "benefits_continuation",
+            "records_archive", "compliance_attestation"
+        ]
+
+    def execute_offboarding(self, employee_id: str, termination_date: date) -> Dict:
+        results = {}
+        for item in self.required_items:
+            handler = getattr(self, f"_process_{item}", None)
+            if handler:
+                results[item] = handler(employee_id, termination_date)
+        return {
+            "employee_id": employee_id,
+            "termination_date": termination_date.isoformat(),
+            "items_completed": sum(1 for v in results.values() if v["status"] == "complete"),
+            "items_pending": sum(1 for v in results.values() if v["status"] == "pending"),
+            "details": results,
+            "compliance_attested": all(v["status"] == "complete" for v in results.values())
+        }
+
+    def _process_system_access_revocation(self, emp_id: str, term_date: date) -> Dict:
+        revoked = []
+        for system_name, system in self.systems.items():
+            try:
+                system.revoke_access(emp_id, term_date)
+                revoked.append(system_name)
+            except Exception as e:
+                return {"status": "pending", "error": str(e), "revoked": revoked}
+        return {"status": "complete", "revoked": revoked}
+}