feat(product-management): cutover to MAF runtime

[Cataldir]

Problem statement

Migrate the product-management-* bounded context (4 services: acp-transformation, assortment-optimization, consistency-validation, normalization-classification) from the legacy BaseRetailAgent runtime internals to the MAF-backed runtime introduced in #981. This is the final bounded context in the R1 cutover order; once it merges and clears the 24-hour steady-state hold, the R1 epic can close and R2 (UI decoupling) becomes unblocked.

This is a hard sunset: legacy runtime imports are deleted in the same PR. There is no coexistence flag.

Required change

For each of product-management-acp-transformation, product-management-assortment-optimization, product-management-consistency-validation, product-management-normalization-classification:

• Replace usage of lib/src/holiday_peak_lib/agents/ internals with the public surface backed by the MAF runtime from feat(lib): MAF runtime adapter behind the existing BaseRetailAgent surface #981.
• Update each main.py and the agent definition to use the MAF-backed seam.
• MCP tool registrations via FastAPIMCPServer remain unchanged in signature; only the underlying runtime changes.
• REST endpoints remain unchanged in shape; migration is internal.
• Per-service Foundry config (FOUNDRY_AGENT_ID_FAST, MODEL_DEPLOYMENT_NAME_FAST, FOUNDRY_AGENT_ID_RICH, MODEL_DEPLOYMENT_NAME_RICH, FOUNDRY_STREAM, PROJECT_ENDPOINT) wired via Helm values + Key Vault refs.
• Three-tier memory bound per ADR-032 (PR docs(adr): ADR-029..033 - architecture contracts (canary, MCP A2A, OTEL, memory, UI on SWA) #978).
• MCP-only A2A enforced (ADR-030, PR docs(adr): ADR-029..033 - architecture contracts (canary, MCP A2A, OTEL, memory, UI on SWA) #978); hop counter wired.
• Delete pre-MAF imports across all four services in the same PR.
• Final R1 cleanup: confirm no service in apps/ still imports the legacy lib/src/holiday_peak_lib/agents/ internals; delete legacy runtime internals from lib/ (public surface stays as a thin re-export over MAF).

Affected components

• apps/product-management-acp-transformation
• apps/product-management-assortment-optimization
• apps/product-management-consistency-validation
• apps/product-management-normalization-classification
• lib/src/holiday_peak_lib/agents (final legacy-internals deletion)

Acceptance criteria (per spec — Acceptance gate per bounded context)

• Contract tests in lib/tests pass.
• All apps/product-management-* unit and integration tests pass.
• Continuous eval baseline (per ADR-028 final schema, PR Add continuous agent evaluation engine #974) within maxDeltaPercent for each agent in this context (advisory until PR Add continuous agent evaluation engine #974 merges).
• AGC canary 5 → 25 → 50 → 100 succeeds in dev, then in staging (per ADR-029, PR docs(adr): ADR-029..033 - architecture contracts (canary, MCP A2A, OTEL, memory, UI on SWA) #978).
• No A2A HTTP detected by scripts/ci/lint_no_a2a_http.py (per ADR-030, PR docs(adr): ADR-029..033 - architecture contracts (canary, MCP A2A, OTEL, memory, UI on SWA) #978).
• Span attribute contract validated by App Insights workbook query (per ADR-031, PR docs(adr): ADR-029..033 - architecture contracts (canary, MCP A2A, OTEL, memory, UI on SWA) #978).
• No pre-MAF imports remain in apps/product-management-acp-transformation, apps/product-management-assortment-optimization, apps/product-management-consistency-validation, apps/product-management-normalization-classification.
• Per-service Foundry config wired via Helm values + Key Vault refs for all four services.
• Legacy lib/ runtime internals deleted in the same PR (public surface remains as thin re-export over MAF).
• No service in apps/ imports the legacy runtime (verified via grep across the entire apps/ tree).
• 24-hour steady-state hold satisfied — closes the R1 epic and unblocks R2 (UI decoupling).

Risks and dependencies

Risk	Mitigation
Assortment-optimization regressions cause poor merchandising decisions surfaced to the UI.	Eval baselines cover assortment-quality metrics; outside tolerance halts the canary.
Consistency-validation regressions cause data-quality issues to leak downstream.	Contract tests cover validation flows; eval baselines cover validation precision/recall.
Final legacy-internals deletion breaks an unmigrated reach-through.	Pre-flight grep across all 26 services + crud-service confirms zero pre-MAF imports before deleting; CI enforces the deletion.
MCP A2A introduces extra latency on multi-hop product-management flows.	Measured pre/post per service; tolerance P95 within 10 %.
Foundry agent ID provisioning fails for any of the 4 services.	Provisioning runs ahead of this PR; failure halts this context.

Blocked by:

• feat(lib): MAF runtime adapter behind the existing BaseRetailAgent surface #981 (lib MAF runtime seam).
• feat(ecommerce): cutover to MAF runtime #988 (ecommerce-* cutover — preceding context per the R1 cutover order).

Blocks: R2 (UI decoupling, file 22-r2-ui-decoupling-swa.md). R2 is a strict downstream of R1's full completion per the S2 sequencing rule.

Evidence links

• apps/product-management-acp-transformation
• apps/product-management-assortment-optimization
• apps/product-management-consistency-validation
• apps/product-management-normalization-classification
• apps/product-management-acp-transformation/src
• apps/product-management-assortment-optimization/src
• apps/product-management-consistency-validation/src
• apps/product-management-normalization-classification/src
• lib/src/holiday_peak_lib/agents
• lib/src/holiday_peak_lib/agents/base_agent.py

ADR impact

• ADR-007 (memory tiers) — refined by ADR-032 (PR docs(adr): ADR-029..033 - architecture contracts (canary, MCP A2A, OTEL, memory, UI on SWA) #978).
• ADR-022 (DAM image-analysis enrichment pipeline boundary) — preserved.
• ADR-024 → ADR-030 (PR docs(adr): ADR-029..033 - architecture contracts (canary, MCP A2A, OTEL, memory, UI on SWA) #978): MCP-only A2A enforced.
• ADR-029 (PR docs(adr): ADR-029..033 - architecture contracts (canary, MCP A2A, OTEL, memory, UI on SWA) #978): AGC canary gates the cutover.
• ADR-031 (PR docs(adr): ADR-029..033 - architecture contracts (canary, MCP A2A, OTEL, memory, UI on SWA) #978): span attribute contract validated.

Branch convention

feature/<issue-id>-product-management-maf-cutover (per ADR-018).

BPMN process

%%{init: {'theme':'base', 'themeVariables': {
  'primaryColor':'#FFB3BA',
  'primaryTextColor':'#000',
  'primaryBorderColor':'#FF8B94',
  'lineColor':'#BAE1FF',
  'secondaryColor':'#BAE1FF',
  'tertiaryColor':'#FFFFFF'
}}}%%
flowchart LR
  A[Analyze Current Code] --> B[Design Change]
  B --> C[Implement on Issue Branch]
  C --> D[Open PR]
  D --> E[Validation and Fixes]
  E --> F[Merge to Main]
  F --> G[Monitor Workflows]
  G --> H[Close Issue and Cleanup]

Loading