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)