210 lines
7.6 KiB
Markdown
210 lines
7.6 KiB
Markdown
# 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`
|