vac-optimizer/CONTEXT.md

Personal Leave Planning

VacOptimizer helps one person turn expiring leave balances into a leave plan across a planning horizon. It combines leave placements with weekends, French public holidays, and ordered planning rules, then reports the resulting time-off periods and any unplaced balances.

Language

Leave entitlement: A quantity of leave granted by a company or generated by an applicable planning rule, with an availability date and an expiry date.

Leave balance: The unspent quantity of a leave entitlement, identified by leave type, availability date, and expiry date. Avoid: vacation day, VacDay

At-risk balance: A leave balance whose expiry date falls between the planning horizon's start and end, including both boundary dates. Its unplaced quantity is at risk of being lost.

Unavoidable expiry: Leave whose expiry date precedes the planning horizon and therefore cannot be saved by that plan.

Deferred balance: The unspent portion of a leave balance that expires after the planning horizon. It needs no ordinary placement in the current plan but remains available to explicit planning rules and supporting placements.

Leave type: The category of leave in a balance: CP (paid leave), RTT (working-time reduction leave), or Other (a user-managed catch-all). Avoid: ANY as a leave type; ANY is only a rule selector.

Planning horizon: The user-selected half-open date interval of at most 12 months within which leave may be placed. It defaults to today's Europe/Paris calendar date through the same date 12 months later.

Working day: A Monday-to-Friday calendar date that is not a French national public holiday. Only working days can receive leave placements.

Public holiday: A French calendar date that cannot receive a leave placement and contributes to a time-off period.

Public-holiday week: A Monday-to-Friday window containing a weekday French public holiday where every other working day is a leave placement.

Public-holiday week value: The distance of every weekday holiday from the nearest weekend, summed within and across completed public-holiday weeks: Monday or Friday is 1, Tuesday or Thursday is 2, and Wednesday is 3.

Leave placement: Using one or more working days from a leave balance on specific dates within the planning horizon.

Supporting placement: A leave placement from a deferred balance that completes a public-holiday week, captures additional adjacent non-working dates, eliminates a short work sequence, or reduces the longest work sequence. Merely extending an existing period by the placed day itself is not sufficient.

Time-off period: A contiguous period containing at least one leave placement together with any adjacent weekends and public holidays, including those immediately outside the planning horizon.

Time-off duration: The number of distinct calendar dates covered by all planned time-off periods.

Non-working-day gain: The distinct weekend and public-holiday dates contained in planned time-off periods. Leave placement dates themselves do not contribute to this gain.

Work sequence: The working days in an interval delimited by planned time-off periods or by the planning horizon edges. Intervening weekends and public holidays neither count nor split the sequence.

Short work sequence: A work sequence of fewer than five working days between two planned time-off periods.

Planning rule: A user instruction that requests leave placements around a calendar opportunity or inside a date window. Its force is either an obligation or a preference.

Obligation rule: A planning rule that every valid plan must satisfy. Obligation rules are resolved jointly; their order only breaks ties between valid plans.

Preference rule: A planning rule that guides placement but may remain unsatisfied to preserve validity or prevent more at-risk leave from expiring.

IF_THEN rule: A planning rule evaluated independently for every French public holiday on its configured weekday. A preference requests a complete pattern around each occurrence when possible; an obligation requires it for every occurrence.

IF_THEN placement mode: before and after fix every requested day on one side; around considers every split with at least one day on each side; auto considers every split, including the all-before and all-after extremes.

TIME_WINDOW rule: A planning rule targeting working days in an inclusive date window. A preference requests up to its configured quantity; an obligation requires exactly that quantity.

Rule priority: The user-defined lexicographic order of preference rules. Each earlier preference is satisfied as far as possible before a later preference is considered.

Rule satisfaction: The relationship in which a plan fulfils a planning rule. One compatible leave placement may contribute to the satisfaction of multiple rules.

Placement provenance: The consumed leave entitlement and every planning rule satisfied by a leave placement.

Plan explanation: A stable account of why an optimization result or incomplete calculation contains its displayed leave placements, expressed through placement provenance, planning objectives, time-off periods, and remaining balances. It reports every contribution of a placement while highlighting the first planning objective that made its position decisive, and describes the displayed plan rather than the calculation history. Avoid: calculation explanation

Calculation trace: The complete, untruncated, ordered history of the planning decisions and candidate evaluations from the same calculation that produced a planning outcome, grouped by calculation phase. It is not reconstructed by replaying the calculation afterward; for an incomplete calculation it ends at the actual interruption point. Avoid: plan explanation

Planning decision: An atomic choice within a calculation phase that accepts, moves, removes, or rejects one or more related leave placements. A joint obligation decision may therefore concern several dates. Avoid: calendar day, step

Candidate evaluation: The comparison the planner actually performs between a possible leave-placement change and the current plan. It belongs to the calculation trace whether the candidate is accepted or rejected.

Candidate date status: The historical relationship between a date and a planning decision: chosen, evaluated and rejected, not examined, or ineligible with a reason. A later counterfactual date analysis never changes this historical status.

Counterfactual date analysis: An on-demand evaluation that changes only the date of one selected leave placement while preserving its leave balance, leave type, and placement provenance. The planner did not necessarily examine that date; the analysis explains a hypothetical alternative but never influences the planning outcome and is not part of the calculation trace. Avoid: candidate evaluation, calculation trace

Conflict explanation: A stable account of why no plan can jointly satisfy a set of obligation rules within the planning horizon and available leave balances. Avoid: plan explanation

Planning conflict: A set of obligation rules that cannot all be satisfied by one plan within the planning horizon and available leave balances.

Invalid planning input: A malformed request that cannot describe a plan, such as a reversed date window. A valid but unsatisfiable request is a planning conflict instead.

Planning outcome: The result of a calculation: invalid input, a planning conflict, an optimization result, or an incomplete calculation.

Incomplete calculation: A calculation stopped before it completed the planning objective order. It may expose its best valid plan but never implies that the obligations conflict.

Planning objective order: The lexicographic quality order applied after joint obligation feasibility: minimize unplaced at-risk leave; satisfy each preference in user order; maximize public-holiday week value; maximize non-working-day gain; minimize the longest work sequence; minimize the total deficit of internal work sequences shorter than five days; minimize supporting placements; consume earlier-expiring balances; then prefer earlier placement dates. Complete holiday weeks therefore precede broader calendar-gain and work-sequence optimization. A lower criterion never degrades a higher one.

Earned leave entitlement: A leave entitlement created for each completed occurrence of an applicable planning rule after its generating time-off period ends. It becomes available the following day, expires one year later, and may fund any later compatible placement. Avoid: reward, bonus days

Optimization result: A valid deterministic plan produced after completing the planning objective order, containing leave placements and their provenance, time-off periods, unsatisfied preference reasons, and remaining balances with reasons. It does not claim mathematical global optimality.

Remaining balance: Any quantity left unspent by the optimization result, reported as unavoidable expiry, an unplaced at-risk balance, or a deferred balance.