agents/api-compatibility: learned load_default backward compat and data_key as API surface

Context:
- PR #2176 added future-annotation-regressors as an optional pipeline config field
  using load_default=[] and data_key kebab-case pattern

Change:
- Added lesson on load_default=[] as backward compatibility pattern for new optional fields
- Added lesson on _clean_parameters not being a regression risk for new config keys
- Added lesson that data_key kebab-case is the API surface (not Python attribute name)

Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Author: Copilot

.github/agents/api-backward-compatibility-specialist.md

@@ -494,3 +494,11 @@ After each assignment:
    Change:
    - Added guidance on <topic>
    ```
+
+### Lessons Learned
+
+**Session 2025 (PR #2176 — annotation regressors forecasting config)**:
+
+- **New pipeline config keys are additive (backward compatible)**: `future-annotation-regressors` uses `load_default=[]`, so existing configs without this key continue to work. This is the correct pattern for new optional pipeline features. When reviewing new schema fields, verify `load_default` (not `required=True`) is set for backward compatibility.
+- **Forecaster `_clean_parameters` is not a regression risk for new config keys**: New pipeline config keys left in `_clean_parameters` are preserved in DataSource attributes. New keys added to the removal list are dropped. Neither path is a breaking change for existing clients; both are intentional design choices. The API Specialist should verify only that the key naming (kebab-case via `data_key`) is consistent with existing keys — it is.
+- **`data_key` kebab-case is the API surface**: The external-facing key is the `data_key` value (`future-annotation-regressors`), not the Python attribute name (`future_annotation_regressors`). Clients sending JSON configs use the kebab-case form. Never check only the Python attribute name when reviewing API contracts for forecasting/reporting config fields.