# Frontend PR Review Checklist v1 (MC #106089)

# Frontend PR Review Checklist v1

**Source spec:** `~/system/docs/published/alai-frontend-engineering-spec-v1-106089.md`  
**MC:** #106089  
**Applies to:** Every ALAI product frontend PR.

Reviewer may mark an item `N/A` only with a reason.

**Scope.** This checklist applies to code the PR actually adds or changes, not retroactively to
the entire product codebase. A pre-existing condition the PR does not touch or extend is not
grounds to block that PR — check the source spec's Appendix B (Known Deviations) first; if the
gap is already tracked there with an open MC, the PR is not blocked on it unless the PR's own
diff extends or depends on the deviated-from behavior. A gap not yet listed in Appendix B
should be flagged and added there, not silently waved through and not used to block an
unrelated PR.

## Build and dependency discipline

- [ ] Lockfile changed only when dependency change is intentional.
- [ ] Dependency install in CI uses frozen lockfile / `npm ci`.
- [ ] `tsc` passes.
- [ ] Lint passes.
- [ ] Production framework build passes (`next build`).
- [ ] No invalid App Router page/layout exports.

## Runtime UX

- [ ] Loading, empty, error, and retry states are implemented for every async area touched.
- [ ] Buttons/links clicked in tests have observable outcomes.
- [ ] Mutations prevent duplicate unsafe submission.
- [ ] A permanent async-init/auth failure (not just a transient one) shows a visible error + retry affordance — never a silently-disabled-forever control.
- [ ] Any manual retry affordance for an SDK/init failure guards against duplicate concurrent retry attempts using state distinct from the failure flag itself (the failure flag is typically reset the instant a retry begins).
- [ ] Error copy is human-readable and does not expose stack traces.

## Auth/session

- [ ] Auth redirect/session flow tested on public/custom domain.
- [ ] Hard navigation to protected deep link remains authenticated after login.
- [ ] Logout clears client and server session state.
- [ ] Cookie attributes are correct for the deployed domain strategy.
- [ ] Any interactive action gated by an auth SDK's ready state derives `disabled`/enabled from the SDK's own ready signal (same condition that gates the SDK provider mount), not a separate synchronous proxy condition.
- [ ] E2E auth-fixture isolation is enforced in the test's own code (`test.use({ storageState: ... })`, explicit `context.clearCookies()`) — not merely documented as a CLI-invocation contract in a comment.

## Cache/versioning

- [ ] Build metadata is present and no-store.
- [ ] Version-skew detection exists for long-lived shells or is tracked as explicit product debt.
- [ ] HTML no-store/revalidate and chunks immutable headers verified on deployed/public URL.

## i18n/a11y/security

- [ ] No new hardcoded user-visible strings in multi-language products.
- [ ] Locale-aware date/amount formatting used.
- [ ] Keyboard navigation and focus states remain valid.
- [ ] CSP/security headers are not weakened.
- [ ] Third-party widget config uses allowed values and is tested.

## Evidence

- [ ] PR includes command output for typecheck/lint/build/tests.
- [ ] PR includes browser evidence for user-facing changes.
- [ ] Known browser console warnings are named; unexpected console errors fail.

## Verdict format

```text
Frontend Spec v1 review: PASS | PARTIAL | BLOCKED
Build gate: pass/fail + command
Browser gate: pass/fail + URL/evidence
Auth/cache/CSP impacted: yes/no
Required follow-ups before merge/promote: ...
```