pedwfrontend/memory-bank/decisions.md

Decisions (ADR-Lite)

Entry Template

date: YYYY-MM-DD
author: <agent|name>
scope: <files/routes/features>
type: decision
rationale: <why>
impact: <user/system/security/i18n/a11y>
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