feat: define video workflow contracts and templates

docs/workflow-contracts.md

@@ -0,0 +1,117 @@
+# 제작 단계의 전달과 완료 기준
+
+## 문서와 양식
+
+이 문서는 제작 입력, 단계별 JSON, 진행 상태, 검토·수정 규칙의 공통 기준이다. 내용과 화면을 작성할 때는 [제작 지침서](short-video-guide.md)의 담당 단계에 필요한 절을 함께 읽는다. 양식·스키마는 실제 생성 프로그램이 아니며, 요청서를 작성한 것과 결과 파일을 받은 것을 구분한다.
+
+- [진행 기록 스키마](../contracts/project.schema.json)와 [빈 진행 기록](../templates/project.json)
+- [단계 결과 스키마](../contracts/artifact.schema.json)와 [14단계 빈 양식](../templates/stages/)
+- [사용자 검토 양식](../templates/review.md)
+
+스키마는 JSON Schema Draft 2020-12다. 파서는 필드·형식·열거값을 검사한다. 완료 판단에는 아래 의미·참조·실제 파일·사용자 응답 확인이 추가로 필요하다. 빈 문자열·배열·null은 미작성 상태를 표현하며, 형식 검사를 통과해도 완료가 아니다. 사용하지 않는 필드를 임의로 추가하지 않는다.
+
+## 제작 입력과 공통 설정
+
+필수 입력은 `topic`, `language`이며 공백만 있거나 빠졌으면 보완한다. 언어 이름·코드를 의미 확인 후 보존한다. 입력 언어로 대본·제목·내레이션·자막을 작성하며 지원되지 않는 언어를 다른 언어로 바꾸지 않는다. 새로운 요청은 저장소에서 유일한 소문자 영숫자·하이픈 `project_id`로 시작한다. 빈 양식의 video-001은 복사 후 실제 식별자로 바꾼다.
+
+공통 설정은 세로 9:16, 최종 180000ms 이내, 각 컷 0ms 초과 5000ms 이하, 스타일 기준 `references/1.png`, TTS `Qwen3-TTS`, conda 환경 `qwen3-tts`, 이미지 모델 `gpt-image-2.5-sunburst`다. 그림체만 참고하고 캠핑 소재·인물·상표를 강제하지 않는다. 쉬운 표현은 대상 시청자를 어린이로 제한하는 규칙이 아니다.
+
+## 저장과 전달
+
+```text
+projects/<project_id>/
+  project.json
+  stages/<stage_id>/r<revision>/artifact.json
+  stages/<stage_id>/r<revision>/review.md
+  media/
+```
+
+모든 데이터 경로는 저장소 루트 기준 상대 경로다. 현재 작업 폴더나 검토 문서의 위치를 기준으로 해석하지 않는다. 외부 실행파일 경로·키·인증정보를 양식에 기록하지 않는다.
+
+단계 결과는 `schema_version`="1.0", `project_id`, `stage_id`, `revision`, `inputs`, `payload`를 가진다. 버전은 1부터 시작하고 이전 결과를 덮어쓰지 않는다. `inputs`는 실제 사용한 선행 결과의 `{stage_id, revision}` 배열이다. 중복·자기 참조·다른 제작물 참조를 금지한다. 14는 13과 검수에서 직접 사용한 유효 선행 결과를 기록한다.
+
+`project.json`의 필드는 `schema_version`, `project_id`, `brief`, `settings`, `stages`, `reviews`다. stages는 아래 14개를 각각 한 번 포함하는 `{stage_id, status, revision, artifact_path, issues}` 배열이다. 결과가 없으면 revision/artifact_path는 null이다. issues는 `{code, message, blocking}` 배열이다. reviews는 네 검토를 각각 한 번 포함하는 `{review_id, decision, artifact_refs, feedback}` 배열이다. artifact_refs는 검토한 `{stage_id, revision}` 배열이고 feedback은 실제 선택·피드백을 기록한 문자열이다.
+
+총괄만 진행 기록의 상태·현재 결과 포인터·승인을 바꾼다. 담당은 자기 단계의 새 버전 결과와 review.md를 제출하고, 준비 여부·미확인 내용·문제를 총괄에 보고한다. 같은 단계·버전을 동시에 작성하지 않는다. review.md는 JSON의 의미를 보존하며 별도로 승인 내용을 바꾸지 않는다.
+
+## 단계별 내용과 완료 기준
+
+필드의 정확한 구조와 타입은 해당 양식·스키마를 사용한다. 배열 순서가 이야기·음성·컷·합성 순서다. 배열 안의 식별자는 유일해야 하고 모든 참조는 같은 제작물의 사용 버전에 존재해야 한다. 빈 필수 텍스트와 미선택 값은 완료 전에 채운다.
+
+| 단계와 양식 | 선행 결과 | 필요한 내용과 완료 확인 |
+|---|---|---|
+| [01-topic](../templates/stages/01-topic.json) | 제작 입력 | 주제 안의 후보·선택 ID·이유. 선택은 후보에 존재하며 topic 승인 필요 |
+| [02-research](../templates/stages/02-research.json) | 01 | 출처·주장·미해결 질문. verified 주장은 실제 확인한 출처를 하나 이상 참조. 불확실한 주장은 uncertain |
+| [03-script](../templates/stages/03-script.json) | 01,02 | 블록별 텍스트·claim_ids·전체 대본·예상 길이. 순서와 내용 일치, 사실 주장은 verified. story 승인 필요 |
+| [04-title](../templates/stages/04-title.json) | 03 | 제목 후보·이유·선택. 대본의 약속과 일치하며 story 승인 필요 |
+| [05-tts-split](../templates/stages/05-tts-split.json) | 03 | 단위별 block_ids·표시/발화 텍스트·발음 메모. 순서·의미·누락·중복 확인 |
+| [06-tts](../templates/stages/06-tts.json) | 05 | 도구·환경·언어·단위 요청. 실제 모델·화자·단위 WAV·통합 WAV·실측 unit_ranges 결과. 전체 파일과 시간 확인 |
+| [07-cuts](../templates/stages/07-cuts.json) | 05,06 | 실측 통합 길이·확인 방법·연속 컷·별도 자막. 전체 음성을 덮고 각 컷 5초 이내. scenes 승인 필요 |
+| [08-scenes](../templates/stages/08-scenes.json) | 03,07 | 각 컷의 설명·시작/끝 상태·카메라·인접 연결. 누락·중복 없음, 연결 이유·상태 일치. scenes 승인 필요 |
+| [09-entities](../templates/stages/09-entities.json) | 03,08 | 인물·배경·고정 특징·컷별 등장 참조. 모든 컷을 정확히 한 번 포함. scenes 승인 필요 |
+| [10-references](../templates/stages/10-references.json) | 02,08,09 | 모델·그림체·스타일/인물/배경 요청, 실제 PNG 결과. 모든 요청 ID와 고정 특징을 다룸. 스타일만 entity_id=null |
+| [11-images](../templates/stages/11-images.json) | 02,03,07,08,09,10 | 컷별 start/end 요청·기준 ID·실제 PNG. 각 컷의 두 위치가 정확히 하나씩 존재, 장면·근거·연속성 일치 |
+| [12-motion](../templates/stages/12-motion.json) | 07,08,11 | 각 컷의 프레임·실제 길이·움직임 요청과 MP4 결과. 모든 컷과 길이·상태 일치 |
+| [13-compose](../templates/stages/13-compose.json) | 03,04,06,07,12 | timeline·통합 음성·자막·제목 요청, 실제 MP4·SRT 결과. 세로 비율·전체 길이·파일·시간·순서 확인 |
+| [14-review](../templates/stages/14-review.json) | 13 및 검수에 사용한 결과 | 6영역 checks·발견·추천. 근거와 수정할 단계·컷. 검수자의 pass와 사용자의 final 승인 구분 |
+
+`*_ms`는 0 이상 정수이고 아직 정하지 않은 시간은 null이다. 완료한 길이는 양수다. 고정 특징·open_questions·각종 *_ids는 문자열 배열이다. accessed_at은 ISO 8601 날짜, blocking/verified는 불리언이다. 그 밖의 텍스트는 문자열이며 selected_id는 미선택 시 null, findings.cut_id는 특정 컷이 아니면 null이다. 실제 사용한 모델·화자는 06 result.model/voice에 기록한다.
+
+## 실제 파일과 시간 확인
+
+media는 `{path, kind, verified, duration_ms, width, height}`다. kind는 audio/image/video, 미확인 값은 null, 검증하지 않은 파일은 verified=false다. 실제 파일 존재·내용 형식·메타데이터를 확인한 경우만 true다. 확장자나 요청 길이만으로 실제 결과를 확인했다고 쓰지 않는다.
+
+- 음성은 WAV, width/height=null, 실제 duration_ms 필요.
+- 이미지는 PNG, duration_ms=null, 실제 width/height 필요.
+- 영상은 MP4, 실제 duration_ms·width·height 필요. 최종 자막은 SRT이며 파일·언어·내용·정렬을 확인한다.
+
+외부 단계의 result=null이면 awaiting_input이다. 부분 결과는 보존하되 요청 항목을 모두 받기 전 complete로 처리하지 않는다. 결과의 unit_id/reference_id/frame_id/cut_id는 요청에 존재해야 한다. 가상 예제 경로는 검증된 실제 파일로 기록하지 않는다.
+
+Qwen3-TTS의 설치 탐색, 모델 로딩, 실제 추론 성공은 다른 확인이다. 기존 환경을 재설치하지 않고 실제 제작 시 모델·화자·언어 지원을 확인한다. 이미지 모델·세로 출력의 지원 여부도 실제 제작에서 확인하며, 확인하지 않은 API 파라미터나 다른 모델을 고정하지 않는다. 영상 생성·합성 엔진은 이번 범위에서 선택하지 않는다.
+
+06의 통합 음성이 시간 기준이다. unit_ranges는 해당 단위의 실제 통합 음성 구간을 기록하며 순서·전체 포함·겹침을 확인한다. 07 cuts는 0부터 통합 음성 끝까지 빈 구간·중복 없이 이어진다. 각 컷은 start_ms < end_ms, end_ms-start_ms <= 5000이다. 긴 문장을 화면 컷으로 나눌 수 있지만 단어·의미를 누락하거나 순서를 바꾸지 않는다.
+
+captions는 컷과 다른 단위다. 여러 컷을 걸칠 수 있으며 0 <= start_ms < end_ms <= 통합 길이, 텍스트·표시 순서를 보존한다. 글자 수 기반 예상 정렬을 실측으로 표시하지 않는다. timing_evidence에 파일 측정·청취·정렬 확인 방법을 적는다. 실제 음성이 180000ms를 넘으면 대본 수정과 story 재승인으로 돌아간다.
+
+## 상태와 네 사용자 검토
+
+| 단계 상태 | 의미 |
+|---|---|
+| pending | 시작 전 |
+| draft | 작성 중 |
+| awaiting_input | 필수 자료·실제 결과·파일 부재 |
+| awaiting_review | 검토 결과 버전을 제시하고 사용자 결정 대기 |
+| complete | 완료 조건과 필요한 사용자 승인 충족 |
+| stale | 사용한 선행 버전의 변경으로 다시 확인해야 함 |
+| failed | 실행·검증 실패가 보고됨 |
+
+기본 흐름은 pending→draft, 자료 부재 시 draft→awaiting_input, 결과 준비 시 draft/awaiting_input→complete 또는 awaiting_review다. 승인 후 complete, 변경 요청·실패 복구는 draft에서 새 버전을 만든다. 그 밖의 전이는 현재 기록을 먼저 확인하고 issues에 이유를 남긴다.
+
+| 검토 ID | 사용자가 확인하는 결과 | 승인 전 진행하지 않는 곳 |
+|---|---|---|
+| topic | 01 각도·범위 | 02 자료 조사 |
+| story | 02 근거와 03 대본·04 제목 | 05 TTS 분할 |
+| scenes | 07 실제 컷·08 연결·09 인물·배경 | 10 기준 이미지 |
+| final | 13 실제 완성본·14 보고 | 제작 완료 선언 |
+
+검토 결정은 pending/approved/changes_requested/stale다. 승인 버전을 artifact_refs로 고정하고 실제 사용자 응답을 feedback에 기록한다. 응답 없음·담당의 추천은 승인이 아니다. 같은 승인 버전으로 재개할 때는 다시 묻지 않는다. 한 검토 묶음 안에서는 준비된 유효 결과로 묶음을 완성할 수 있다. 예를 들어 07 결과로 08·09를 준비한 뒤 scenes 검토를 요청하되, 승인 전에 10으로 넘어가지 않는다.
+
+## 재개와 수정
+
+재개는 brief·현재 포인터·버전별 결과·승인·실제 파일·참조의 유효성을 확인한 뒤 가장 앞선 미해결 작업부터 이어간다. 오래된 버전·다른 제작물의 결과를 섞지 않는다. 같은 주제의 새 제작과 기존 제작의 재개를 구분한다.
+
+수정은 새 r<revision>을 만든다. inputs의 실제 관계를 따라 영향을 받는 후속 결과를 stale로 표시하고, 해당 결과를 승인한 검토도 stale로 표시한다. 변경과 관계없는 결과는 유지한다. 가령 04 제목만 변경하면 이를 쓰는 13·14와 story/final 검토는 재확인하지만, 05–12의 기존 음성·장면·이미지를 무조건 재생성하지 않는다. story 승인을 받은 뒤 기존 미디어와 새 제목을 연결할 수 있다.
+
+언어 변경은 해당 언어를 사용하는 조사·대본·제목·발화·자막과 후속 결과를 재검토한다. 단순한 표시 수정이 의미·음성을 바꾸는지 확인하고 영향 범위와 보존할 결과를 보고한다. 승인 경계가 다시 열리면 새 후속 작업 전 재승인을 받는다. 이전 검토와 결과는 버전별 review.md에 보존한다.
+
+## 검수의 판정과 근거
+
+14의 area는 story/visual/audio/captions/timing/consistency, verdict는 pass/fail/not_checked다. 모든 영역의 실제 근거가 있어야 하며 미확인 영역을 pass로 만들지 않는다. findings는 blocking/minor, 설명, 수정할 stage_id와 cut_id를 기록한다. 추천은 pass/revise/incomplete다.
+
+pass는 여섯 영역 모두 pass이고 blocking 발견이 없을 때만 가능하다. 실제 완성본이 없거나 볼 수 없으면 incomplete다. 제작 지침의 [최종 영상 검토](short-video-guide.md#최종-영상-검토) 질문을 기존 checks.evidence에 연결하며 새 필드·승인 지점을 만들지 않는다.
+
+## 형식 검사와 의미 확인의 경계
+
+스키마는 잘못된 필드·타입·단계·상태, 진행 기록의 14단계/4검토 구성, 다른 도구명, 음성·이미지의 해당 없는 메타데이터, 근거 없는 pass 구조를 검사한다. 주제·언어의 실사용 값, 배열별 식별자·참조의 유효성, 선택 ID, 대본 일치, 파일 실존·언어 지원, 승인 진위, 실제 시간·길이·화면 판독성, 종속 결과의 stale 처리는 담당과 총괄이 별도로 확인한다.
+
+파싱·스키마 검사만으로 Codex의 실제 에이전트·스킬 탐색이나 미디어 생성을 확인했다고 쓰지 않는다. [공식 에이전트 형식](https://learn.chatgpt.com/docs/agent-configuration/subagents#custom-agents)과 [스킬 위치](https://learn.chatgpt.com/docs/build-skills#where-to-save-skills)를 따른다. 실제 호출 환경에서 목록에 보이는지 확인하고, 보이지 않으면 프로젝트 루트에서 새 세션으로 탐색한다.