리포트 봉투를 계약으로 고정했다

미결 항목 jin 27번에서 정어진 님이 물어온 것 — 적재를 짜려는데 report.json 스키마가 조용히 바뀔 수 있다. 그럴 만한 지적이었다. agent/report-contract.md 머리에 내가 「이 문서는 사본이고 정본은 코드」라고 적어 두었기 때문이다. 읽는 쪽이 셋(적재·읽기 API·화면)인 JSON 에 그렇게 적어 두면, 키 하나를 지우는 변경이 에이전트 테스트를 전부 통과하고 백엔드 배포 뒤 실서버에서만 드러난다.

한 것

필드 목록의 정본	agent/contracts/report_schema.yaml — 봉투 20키 · result 8키 · breakdown[] 11키 · skipped[] 3키
봉투가 버전을 말한다	최상위 schema_version(지금 "1.0"). 추가는 1.1, 삭제·뜻 변경은 2.0 + 미결 항목으로 미리 알림
어긋나면 빨개진다	tests/test_report_contract.py 가 production build_report 의 산출과 그 yaml 을 맞춰 본다
성공 보고의 보장	완료 보고가 succeeded 면 report_key 가 항상 있다
신뢰도 자리	keypoint_quality.swing_side_valid_ratio

검사할 수 있게 하려고 봉투를 떼어냈다. 리포트 딕셔너리가 analyze_one 안에 있으면 키 하나를 확인하는 데 S3·영상·판정 모델이 다 필요하고, 그러면 확인하지 않게 된다. build_report 로 떼어 두면 합성 키포인트만으로 봉투가 검사된다. 계약 파일을 스텁 dict 와 맞춰 보는 것은 의미가 없어서, 검사는 production 함수의 산출을 본다 — 일부러 키 이름을 바꿔 빨개지는 것도 확인했다.

정정 둘

(1) 「정본은 코드」. 값이 어떻게 만들어지는지는 여전히 코드가 정본이지만, 필드가 있는가 없는가는 이제 yaml 이다. 둘을 테스트가 묶는다. 사본을 하나 더 두는 것이 아니라, 사본이 갈라지는 것을 막는 장치다.

(2) 「자리를 못 실어도 성공으로 보고한다」. 워커 주석과 로드맵에 그렇게 적혀 있었다. 근거는 “작업이 running 으로 남는 것이 더 나쁘다”였는데, 적재가 report_key 로 S3 를 읽기로 정해진 지금은 키 없는 succeeded 가 영원히 빈 리포트다 — 작업은 끝난 것으로 닫히고, 화면은 아무것도 못 찾고, 사용자에게는 다시 시도할 방법조차 안 보인다. 실패로 드러내면 적어도 재시도가 된다. 네 가지 경우(자리 파일 없음·빈 목록·다른 버킷·두 건이라 모호)를 검사가 붙들고 있다.

신뢰도는 이미 재고 있었다

계약 3장 4)의 산출물 넷 중 신뢰도를 담을 자리가 비어 있었다. 그런데 품질 게이트(features.check_quality)가 이미 그 값을 재고 통과 여부만 남기고 버리고 있었다 — 71%로 겨우 통과한 클립과 여유 있게 통과한 클립을 읽는 쪽이 구분할 수 없었다. 게이트와 봉투가 같은 함수(gate_ratio)를 쓰게 하고 그 값을 실었다. 비율을 두 번 계산하면 게이트가 0.72로 통과시킨 입력을 봉투가 0.61이라고 적는 일이 생긴다.

🔴 키포인트 신뢰도 평균이 아니다. 포즈 모델이 top-down 이라 엉뚱한 박스를 줘도 자신 있게 관절을 낸다 — 평균이 높은 것은 「잘 잡았다」가 아니다. 「누구를 쟀는가」는 subject 블록이 따로 답한다.

features 가 아니라 형제 블록으로 낸 것도 의도다. features 에 키를 더하면 판정 입력이 달라져 그때까지의 평가와 비교가 끊긴다.

남은 것

적재 구현과 breakdown[] 을 담을 테이블 선택은 정어진 님 몫이다. 필드 목록은 못박아 두었으니 컬럼을 거기 맞추면 된다. 상세와 정본은 미결 항목 jin 27번.