feat(core-api): add verification pipeline with vertex attire adapter

docs/MILESTONES/M4/planning/m4-core-api-frontend-guide.md

@@ -118,6 +118,82 @@ Authorization: Bearer <firebase-id-token>
 }
 ```
 
+## 4.4 Create verification job
+1. Route: `POST /core/verifications`
+2. Auth: required
+3. Purpose: enqueue an async verification job for an uploaded file.
+4. Request body:
+```json
+{
+  "type": "attire",
+  "subjectType": "worker",
+  "subjectId": "<worker-id>",
+  "fileUri": "gs://krow-workforce-dev-private/uploads/<uid>/file.pdf",
+  "rules": {
+    "dressCode": "black shoes"
+  }
+}
+```
+5. Success `202` example:
+```json
+{
+  "verificationId": "ver_123",
+  "status": "PENDING",
+  "type": "attire",
+  "requestId": "uuid"
+}
+```
+6. Current machine processing behavior in dev:
+- `attire`: live vision check using Vertex Gemini Flash Lite model.
+- `government_id`: third-party adapter path (falls back to `NEEDS_REVIEW` if provider is not configured).
+- `certification`: third-party adapter path (falls back to `NEEDS_REVIEW` if provider is not configured).
+
+## 4.5 Get verification status
+1. Route: `GET /core/verifications/{verificationId}`
+2. Auth: required
+3. Purpose: polling status from frontend.
+4. Success `200` example:
+```json
+{
+  "verificationId": "ver_123",
+  "status": "NEEDS_REVIEW",
+  "type": "attire",
+  "review": null,
+  "requestId": "uuid"
+}
+```
+
+## 4.6 Review verification
+1. Route: `POST /core/verifications/{verificationId}/review`
+2. Auth: required
+3. Purpose: final human decision for the verification.
+4. Request body:
+```json
+{
+  "decision": "APPROVED",
+  "note": "Manual review passed",
+  "reasonCode": "MANUAL_REVIEW"
+}
+```
+5. Success `200` example:
+```json
+{
+  "verificationId": "ver_123",
+  "status": "APPROVED",
+  "review": {
+    "decision": "APPROVED",
+    "reviewedBy": "<uid>"
+  },
+  "requestId": "uuid"
+}
+```
+
+## 4.7 Retry verification
+1. Route: `POST /core/verifications/{verificationId}/retry`
+2. Auth: required
+3. Purpose: requeue verification to run again.
+4. Success `202` example: status resets to `PENDING`.
+
 ## 5) Frontend fetch examples (web)
 
 ## 5.1 Signed URL request
@@ -163,5 +239,7 @@ const data = await res.json();
 2. Aliases exist only for migration compatibility.
 3. `requestId` in responses should be logged client-side for debugging.
 4. For 429 on model route, retry with exponential backoff and respect `Retry-After`.
-5. Verification workflows (`attire`, `government_id`, `certification`) are defined in:
+5. Verification routes are now available in dev under `/core/verifications*`.
+6. Current verification processing is async and returns machine statuses first (`PENDING`, `PROCESSING`, `NEEDS_REVIEW`, etc.).
+7. Full verification design and policy details:
    `docs/MILESTONES/M4/planning/m4-verification-architecture-contract.md`.