refinement phase 3

dev/contracts/domains/identity-auth.md

@@ -128,3 +128,14 @@
 
 ## Changelog
 - b2 — initial contract (phone-OTP auth, sessions, `/me`, role selection).
+
+---
+
+## Refinement phase 3 additions (REQ-002/003)
+
+- **`RequestOtpResult`** gains `codeLength` (6) and `expiresInSeconds` (60) so the OTP box count + expiry
+  hint are contract-driven.
+- **`verify_otp` failures** now carry a stable machine `code` on the envelope: `otp_invalid` (wrong **or**
+  expired — collapsed for anti-enumeration) and `otp_locked` with `data: { retryAfterSeconds }` on lockout.
+  The coded-error envelope is `{ isSuccess: false, statusCode: 400, message, code, data? }` (the optional
+  `code` is omitted from every other response).