From 97cde880c09c8ce1a75e5c16badbba389f9fab6f Mon Sep 17 00:00:00 2001
From: robbond <rob@rdbsolutions.co.uk>
Date: Thu, 9 Apr 2026 15:17:44 +0100
Subject: [PATCH] docs(breadcrumbs): record map precedence and callback
 invariants

---
 memory-bank/change-log.md | 27 +++++++++++++++++++++++++++
 memory-bank/decisions.md  | 37 +++++++++++++++++++++++++++++++++++++
 2 files changed, 64 insertions(+)

diff --git a/memory-bank/change-log.md b/memory-bank/change-log.md
index 8d7a2f8a..8b05ce3b 100644
--- a/memory-bank/change-log.md
+++ b/memory-bank/change-log.md
@@ -833,6 +833,33 @@ Follow-ups:
 - Next smaller slice candidate: helper-level assertion for missing/undefined representation dependency values yielding no renderer output regressions.
 - Next larger slice candidate: evaluate whether remaining `/newappeal` edge branch can be absorbed into mapped grouping without reducing readability or explicitness.
 
+### CL-22541-Z: breadcrumbs closure slice 1 — mapped-route precedence/callback invariants decision
+
+date: 2026-04-09  
+author: Cline  
+scope: `memory-bank/decisions.md`  
+type: change  
+rationale: Execute closure slice 1 by documenting explicit architectural invariants for breadcrumb mapped-route precedence and callback injection contracts so future refactors remain safe and auditable.  
+impact: Documentation/governance hardening only; no runtime route/auth/session/API/EN-CY/a11y behavior change.
+status: completed
+
+Summary:
+
+- Added `D-006` to `memory-bank/decisions.md`.
+- Captured accepted invariant contracts for:
+    - explicit breadcrumb map precedence ordering (9 groups)
+    - callback/state behavior dependency injection requirement (no ad-hoc inline reintroduction)
+    - structure test guardrails as contract checks for intentional future changes.
+
+Validation:
+
+- Documentation consistency review against current breadcrumb map structure and phase22 structure test expectations.
+
+Follow-ups:
+
+- Closure slice 2: add focused negative-path representation map/dependency tolerance test coverage.
+- Closure slice 3: resolve and guard remaining `/newappeal` inline edge branch treatment.
+
 ### CL-00X: 22500 `components/elements/index.js` Phase 1 helper extraction
 
 date: 2026-04-07  
diff --git a/memory-bank/decisions.md b/memory-bank/decisions.md
index 34f90d18..5f3c4068 100644
--- a/memory-bank/decisions.md
+++ b/memory-bank/decisions.md
@@ -170,3 +170,40 @@ Related:
 - `context/test-coverage-map.md`
 - `context/current-state-scorecard.md`
 - `memory-bank/open-questions.md` (Q-002)
+
+---
+
+### D-006: Breadcrumb mapped-route precedence and callback injection invariants
+
+date: 2026-04-09  
+author: Cline  
+scope: `components/breadcrumbs.js`, `lib/routing/{breadcrumbRendererFactories,breadcrumbRouteMaps}.js`, `tests/phase22/breadcrumbs-route-map-structure.test.cjs`  
+type: decision  
+rationale: Priority 3 route-state extraction moved most breadcrumb behavior into grouped mapped renderers; explicit invariants are required so future refactors do not silently reorder precedence or regress callback/state behavior.  
+impact: Improves regression safety for search/case/myportal navigation by making map-order and callback injection constraints explicit.  
+status: accepted
+
+Decision:
+
+- Preserve explicit mapped renderer precedence in this order unless a tested migration plan is approved:
+    1. `simpleRouteRenderersByPath`
+    2. `simpleLinkTextPairRenderersByPath`
+    3. `simpleMyPortalRouteRenderersByPath`
+    4. `newAppealRouteRenderersByPath`
+    5. `callbackRouteRenderersByPath`
+    6. `stepBackRouteRenderersByPath`
+    7. `representationRouteRenderersByPath`
+    8. `caseDetailRouteRenderersByPath`
+    9. `detailAndAccountRouteRenderersByPath`
+- Callback/stateful breadcrumb behavior must be dependency-injected into factory groups (e.g. `onBack`, step-back callbacks, representation submit/questionnaire callbacks) rather than recreated as ad-hoc inline path branches.
+- Structural guardrails in `tests/phase22/breadcrumbs-route-map-structure.test.cjs` are considered contract tests for these invariants and must be updated in the same commit as intentional precedence/callback changes.
+
+Consequences:
+
+- Future breadcrumb extraction work remains predictable and test-auditable.
+- Accidental map-order drift or callback behavior inlining should be caught early by structure/helper tests.
+
+Related:
+
+- `memory-bank/change-log.md` (CL-22541-V, CL-22541-W, CL-22541-Y)
+- `tests/phase22/breadcrumbs-route-map-structure.test.cjs`