# 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)