Merge branch 'main' of gitlab.nessar.fr:nessar/vac-optimizer

CONTEXT.md

@@ -87,6 +87,32 @@ The relationship in which a plan fulfils a planning rule. One compatible leave p
 **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.