feat(docs): add explanation for separating plan explanations from calculation traces

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.
 

docs/adr/0004-separate-plan-explanation-from-calculation-trace.md

@@ -0,0 +1,3 @@
+# Separate Plan Explanations from Calculation Traces
+
+VacOptimizer provides a stable plan explanation separately from the complete, untruncated calculation trace captured during the same planning run; on-demand counterfactual date analysis is identified as hypothetical and never presented as trace history. Explanation and tracing must not alter the planning outcome, so trace instrumentation is excluded from the planner deadline and the result may appear before the latest run's in-memory trace finishes loading; this narrows ADR 0003's ten-second hard limit to planning work rather than end-to-end trace delivery. This accepts additional transient memory and wall-clock time instead of inventing scalar day scores, truncating history, or reconstructing a trace by replay.