fix(agent): 근로자 안내 실패를 HR 검토로 안전하게 전환

[hywznn]

Closes #42

왜 필요한가요?

2026-08-13 E2E QA에서 Language Assistant가 미구성되거나 대상 언어 생성에 실패해도 Renewal Graph가 한국어·영어 placeholder를 근로자 발송문으로 확정하는 문제가 확인됐습니다.

이 경로는 alien_registration_number, both_missing 같은 내부 Slot·검증 키까지 노출할 수 있었습니다. 원인은 LanguageGuideBridge 실패를 placeholder로 숨긴 뒤 mark_ask_worker()가 발송 가능한 문장을 새로 만드는 fail-open 동작이었습니다.

무엇이 바뀌나요?

• Language Assistant 미구성·호출 예외·검토 필요 결과를 fail-closed 처리
• 안전하지 않은 안내는 다음 결과로 반환
  • outcome=REVIEW_REQUIRED
  • status=READY_FOR_REVIEW
  • workerRequestMessage=null
  • caseSignals=["REVIEW_WORKER_GUIDE"]
• 응답에 발송 차단 상태를 추가
  • guideReviewRequired
  • guideFailureCode
• 정상 생성·검증을 통과한 쉬운 한국어와 대상 언어만 WAITING_WORKER로 사용
• 내부 Slot·문서 조합 키로 placeholder 근로자 문장을 만들던 로직 제거

응답 예시

{
  "status": "READY_FOR_REVIEW",
  "outcome": "REVIEW_REQUIRED",
  "scenario": "ask_worker",
  "workerRequestMessage": null,
  "guideReviewRequired": true,
  "guideFailureCode": "LANGUAGE_ASSISTANT_NOT_CONFIGURED",
  "caseSignals": ["REVIEW_WORKER_GUIDE"]
}

OCR 재개 계약 테스트

같은 taskId를 사용해 아래 흐름을 API 테스트로 고정했습니다.

1차 Renewal run
→ 정상 베트남어 안내
→ WAITING_WORKER

2차 Renewal run
+ 같은 taskId
+ 승인 OCR 5개 필드
+ 계약·근무 Slot
→ REVIEW_REQUIRED
→ READY_FOR_REVIEW
→ 등록 문서 4종 status=generated
→ OCR 여권번호가 통합신청서 values에 반영

이 테스트는 AI가 Server 이벤트를 소비한다는 뜻이 아닙니다. WorkerDocument 채택·OCR 실행/승인·동일 Task 재호출·생성 파일 영속화는 Server #160 범위입니다.

검증

• 현재 develop 기반 전체: 628 passed, 6 failed, 1 skipped
  • 실패 4건: 기본 설치에 Qdrant 선택 의존성 없음
  • 실패 2건: macOS에 PowerShell 없음
• 환경 의존 파일 분리 core: 617 passed, 1 skipped
• 변경 Python 파일 Ruff: 통과
• git diff --check: 통과

병합 전 확인

• Server가 REVIEW_WORKER_GUIDE를 자동 발송하지 않고 HR 검토로 처리
• Server가 신규 guideReviewRequired, guideFailureCode를 허용
• Knowledge #51의 Catalog 표시명 계약과 후속 연결
• 실제 Language Provider 성공/실패 staging smoke
• Server #160의 승인 OCR → 동일 Task 재호출 → 생성 파일 저장 smoke

포맷 주의

현재 Renewal 등록 문서 4종은 실제 구현대로 format=hwp입니다. HWPX가 데모 완료 조건이면 Server 변환 또는 AI generator 변경을 별도로 결정해야 합니다. 이 PR은 HWPX 완료를 주장하지 않습니다.

Refs fowoco/server#160
Refs fowoco/knowledge#51

[hywznn]

Server origin/main 호환성을 추가 확인했습니다.

현재 Server는 아래 이유로 이 PR의 fail-closed 응답을 거부합니다.

1. REVIEW_WORKER_GUIDE가 허용 Case Signal 목록에 없음
2. scenario=ask_worker이면 workerRequestMessage를 무조건 요구함
3. 신규 guideReviewRequired, guideFailureCode를 아직 모델·감사 이력에 보존하지 않음

Server 후속 이슈를 별도로 만들었으며, 해당 계약 반영 전까지 이 PR은 Draft를 유지합니다. AI 코드·단위/API 테스트는 완료됐지만 현재 배포 Server와의 실통신은 아직 통과 조건이 아닙니다.