# Decisions (ADR-Lite) ## Entry Template ``` date: YYYY-MM-DD author: scope: type: decision rationale: impact: status: proposed|accepted|superseded Decision: Consequences: Related: ``` --- ### D-001: AI Governance Bundle Structure date: 2026-03-11 author: Cline scope: .clinerules, ai-prompts/, context/, memory-bank/ type: decision rationale: Establish a durable AI collaboration system aligned to repository risks and delivery model. impact: Improves consistency, review quality, and safety for auth/i18n/public-service flows. status: accepted Decision: Adopt four artifact pillars: 1. `.clinerules` for operating constraints, 2. `ai-prompts/` for reusable task templates, 3. `context/` for architecture/domain references, 4. `memory-bank/` for persistent project knowledge. Consequences: - AI/human contributors use a shared protocol. - Non-trivial changes require memory-bank updates. Related: - `context/project-overview.md` - `memory-bank/README.md` --- ### D-002: Relay forwarding hardening policy baseline (P2-S3) date: 2026-03-24 author: Cline scope: `pages/api/middleware/relayForwarding.js`, relay-backed endpoint handlers type: decision rationale: Consolidate relay reliability behavior into one shared policy so retries, timeouts, and logging are predictable and safe across all migrated GET flows. impact: Improves resilience and observability while reducing risk of accidental overload, noisy duplicate logs, and inconsistent retry behavior per endpoint. status: accepted Decision: - Shared relay defaults and bounds are centrally enforced in middleware: - timeout default `8000ms`, clamped to `100..30000ms` - retries default `2`, clamped to `0..4` - retry delays clamped to `0..5000ms` - Retry classification is explicit: - retryable: `408`, `429`, `5xx`, selected network/transient transport error codes - non-retryable: deterministic client/auth statuses (`400`, `401`, `403`, `404`, `422`) and other explicit non-retryable HTTP statuses - Structured relay logs are redacted and emitted once per failure path: - relay layer emits retry/failure structured events - endpoint catch logging avoids duplicate emission when relay layer already logged terminal failure Consequences: - Endpoint contracts remain unchanged while reliability behavior is normalized. - Future relay policy changes should be made in one location and validated via phase21 hardening tests. Related: - `memory-bank/change-log.md` (CL-030, CL-031) - `tests/phase21/relay-forwarding-hardening.test.cjs` --- ### D-003: Relay policy changes require governance gate + rollout evidence date: 2026-03-24 author: Cline scope: relay policy changes (`pages/api/middleware/relayForwarding.js`) and related rollout docs type: decision rationale: Prevent regression risk from reliability-policy changes by requiring explicit pre-merge controls and operational smoke evidence. impact: Improves production safety and auditability for relay behavior changes without altering endpoint API contracts. status: accepted Decision: - Any relay policy change (timeout/retry/logging classification) must include: - explicit PR governance checklist completion - non-prod smoke matrix evidence for deterministic + transient classes - rollback path and monitoring checks - Policy and rollout guidance source-of-truth is maintained in: - `context/runbook.md` Relay Hardening Rollout Playbook - memory-bank change/decsion/pattern entries for traceability Consequences: - Relay hardening changes are treated as operationally sensitive even when endpoint contracts do not change. - Future contributors have a repeatable gate for shipping policy changes safely. Related: - `context/runbook.md` - `memory-bank/change-log.md` (CL-032) --- ### D-004: Runtime canonicalization decision needed (`server.js` vs `server/server.js`) date: 2026-03-25 author: Cline scope: runtime startup path, scripts, runbook documentation type: decision rationale: Architecture/debt review identifies persistent ambiguity from dual server entrypoints, increasing operational drift risk. impact: Affects release reliability, troubleshooting clarity, onboarding consistency, and change safety for runtime-affecting work. status: proposed Decision: - Adopt one explicit canonical runtime startup path for dev/test/prod and document it in runbook + scripts. - Mark the non-canonical server entrypoint as deprecated (or remove when safe) with rollback instructions. Consequences: - Reduces deployment and incident-response ambiguity. - Requires coordinated validation across environments before deprecating the alternate path. Related: - `memory-bank/architect-review.md` - `context/architecture.md` - `context/runbook.md` --- ### D-005: Introduce CI baseline checks for high-risk parity/coverage gates date: 2026-03-25 author: Cline scope: CI policy for architecture/debt hardening lanes type: decision rationale: High-value focused tests now exist but are not yet fully institutionalized as explicit baseline gates for parity-sensitive change safety. impact: Improves release confidence and reduces regression drift in auth/i18n/high-risk integration paths. status: proposed Decision: - Add baseline CI checks for: - `npm run lint` - phase22 aggregate high-risk checks (`tests/phase22/index.test.cjs`) - EN/CY parity validation checks (initial rewrite parity scope) Consequences: - Tightens merge discipline for high-risk changes. - May require staged rollout to avoid pipeline disruption while stabilizing flaky areas. 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`