feat: add versioned Blender production contracts

2026-10-09 23:18:07 +09:00
parent b2b37a1105
commit d4f1a800aa
52 changed files with 1601 additions and 224 deletions
@@ -14,7 +14,7 @@

 필수 입력은 `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`다. 그림체만 참고하고 캠핑 소재·인물·상표를 강제하지 않는다. 쉬운 표현은 대상 시청자를 어린이로 제한하는 규칙이 아니다.
+공통 설정은 세로 9:16, 최종 180000ms 이내, 각 컷 0ms 초과 5000ms 이하, 스타일 기준 `references/1.png`, TTS `Qwen3-TTS`, conda 환경 `qwen3-tts`, 새 제작의 시각 엔진 `Blender`다. 단순 배경·부드러운 조명·선명한 형태의 교육용 3D를 사용하며 원본의 단순 형태·정돈된 색을 참고한다. 원본을 보존하고 평면 복제와 캠핑 소재·인물·상표를 강제하지 않는다. 쉬운 표현은 대상 시청자를 어린이로 제한하는 규칙이 아니다.

 ## 저장과 전달

@@ -28,7 +28,7 @@ projects/<project_id>/

 모든 데이터 경로는 저장소 루트 기준 상대 경로다. 현재 작업 폴더나 검토 문서의 위치를 기준으로 해석하지 않는다. 외부 실행파일 경로·키·인증정보를 양식에 기록하지 않는다.

-단계 결과는 `schema_version`="1.0", `project_id`, `stage_id`, `revision`, `inputs`, `payload`를 가진다. 버전은 1부터 시작하고 이전 결과를 덮어쓰지 않는다. `inputs`는 실제 사용한 선행 결과의 `{stage_id, revision}` 배열이다. 중복·자기 참조·다른 제작물 참조를 금지한다. 14는 13과 검수에서 직접 사용한 유효 선행 결과를 기록한다.
+단계 결과는 `schema_version`="1.1"(새 제작) 또는 "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은 실제 선택·피드백을 기록한 문자열이다.

@@ -47,11 +47,11 @@ projects/<project_id>/
 | [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 승인 필요 |
+| [08-scenes](../templates/stages/08-scenes.json) | 03,07 | 각 컷의 설명·시작/끝 상태·카메라·인접 연결과 preview(대표 PNG·짧은 MP4·.blend). 누락·중복 없음, 연결 이유·상태 일치. 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 결과. 모든 컷과 길이·상태 일치 |
+| [10-references](../templates/stages/10-references.json) | 02,08,09 | Blender·RenderProfile·스타일/인물/배경/물체 요청, 실제 .blend·PNG 결과. 모든 요청 ID와 실제 오브젝트/컬렉션·고정 특징 확인. style/object만 entity_id=null |
+| [11-images](../templates/stages/11-images.json) | 02,03,07,08,09,10 | 컷별 start/end·Scene 이름·논리 프레임·기준 ID 요청, 실제 .blend·PNG. 각 컷의 두 위치가 정확히 하나씩 존재, 장면·근거·연속성 일치 |
+| [12-motion](../templates/stages/12-motion.json) | 07,08,11 | 11 실제 .blend·동일 RenderProfile·Scene·프레임 범위·실측 길이·움직임 요청과 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 승인 구분 |

@@ -67,7 +67,7 @@ media는 `{path, kind, verified, duration_ms, width, height}`다. kind는 audio/

 외부 단계의 result=null이면 awaiting_input이다. 부분 결과는 보존하되 요청 항목을 모두 받기 전 complete로 처리하지 않는다. 결과의 unit_id/reference_id/frame_id/cut_id는 요청에 존재해야 한다. 가상 예제 경로는 검증된 실제 파일로 기록하지 않는다.

-Qwen3-TTS의 설치 탐색, 모델 로딩, 실제 추론 성공은 다른 확인이다. 기존 환경을 재설치하지 않고 실제 제작 시 모델·화자·언어 지원을 확인한다. 이미지 모델·세로 출력의 지원 여부도 실제 제작에서 확인하며, 확인하지 않은 API 파라미터나 다른 모델을 고정하지 않는다. 영상 생성·합성 엔진은 이번 범위에서 선택하지 않는다.
+Qwen3-TTS의 설치 탐색, 모델 로딩, 실제 추론 성공은 다른 확인이다. 기존 환경을 재설치하지 않고 실제 제작 시 모델·화자·언어 지원을 확인한다. Blender 버전·렌더링 지원·실제 원본 재열기·PNG/MP4 출력은 따로 확인한다. 설치 확인만으로 성공을 주장하지 않는다. 합성은 승인된 기존 Remotion + FFmpeg 경로를 쓰며 전역 환경 재설치·무단 도구 대체를 하지 않는다.

 06의 통합 음성이 시간 기준이다. unit_ranges는 해당 단위의 실제 통합 음성 구간을 기록하며 순서·전체 포함·겹침을 확인한다. 07 cuts는 0부터 통합 음성 끝까지 빈 구간·중복 없이 이어진다. 각 컷은 start_ms < end_ms, end_ms-start_ms <= 5000이다. 긴 문장을 화면 컷으로 나눌 수 있지만 단어·의미를 누락하거나 순서를 바꾸지 않는다.

@@ -91,7 +91,7 @@ captions는 컷과 다른 단위다. 여러 컷을 걸칠 수 있으며 0 <= sta
 |---|---|---|
 | topic | 01 각도·범위 | 02 자료 조사 |
 | story | 02 근거와 03 대본·04 제목 | 05 TTS 분할 |
-| scenes | 07 실제 컷·08 연결·09 인물·배경 | 10 기준 이미지 |
+| scenes | 07 실제 컷·08 연결과 실제 대표 PNG/짧은 MP4·09 인물·배경 | 정식 10–12 제작 |
 | final | 13 실제 완성본·14 보고 | 제작 완료 선언 |

 검토 결정은 pending/approved/changes_requested/stale다. 승인 버전을 artifact_refs로 고정하고 실제 사용자 응답을 feedback에 기록한다. 응답 없음·담당의 추천은 승인이 아니다. 같은 승인 버전으로 재개할 때는 다시 묻지 않는다. 한 검토 묶음 안에서는 준비된 유효 결과로 묶음을 완성할 수 있다. 예를 들어 07 결과로 08·09를 준비한 뒤 scenes 검토를 요청하되, 승인 전에 10으로 넘어가지 않는다.
@@ -115,3 +115,15 @@ pass는 여섯 영역 모두 pass이고 blocking 발견이 없을 때만 가능
 스키마는 잘못된 필드·타입·단계·상태, 진행 기록의 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)를 따른다. 실제 호출 환경에서 목록에 보이는지 확인하고, 보이지 않으면 프로젝트 루트에서 새 세션으로 탐색한다.
+
+## Blender 전환과 대표 품질 검토
+
+[전달 형식](contracts.md)의 1.1 필드·타입·열거값을 사용한다. 새 양식은 1.1이며 기존 1.0의 정의·승인·실제 결과를 보존하고 선행 자료로 참조한다. 프로젝트 진행 상태·승인 열거값과 14단계·8역할·15스킬·네 검토는 그대로다.
+
+scene-director가 08에서 대표 Scene의 상태·카메라·해설 목적을 정하고 visual-designer/video-editor의 해당 책임으로 제한된 대표 .blend·PNG·짧은 MP4를 준비한다. 결과는 08 preview와 같은 버전 review.md에 기록한다. 이 예외는 scenes 승인 전에 품질을 검토하는 근거 제작만 허용한다. 정식 10–12를 준비·완료했다고 기록하거나 전체 제작을 진행하지 않는다. 대표 샘플의 실제 파일과 단순 배경·부드러운 조명·선명한 형태·변화 판독성을 07/08/09의 같은 scenes 검토에서 제시한다. 추가 승인 지점은 없다. 샘플이나 장면 변경은 08 새 버전에 기록하고 영향을 받는 09와 승인 묶음을 갱신한다.
+
+새 08·09 승인 후 10은 모델·재질·고정 자산을, 11은 컷별 Scene·끝점 상태와 PNG를, 12는 같은 원본·Scene·RenderProfile에서 [start_frame,end_frame) 구간을 렌더링한다. 같은 컷 start/end는 같은 Scene이며 continuous는 실제 경계 상태가 같아야 한다. cut 경계는 Scene을 구별하고 캐시에 Scene 이름을 포함한다. 12의 프레임 수×1000/fps는 요청·실측 컷 길이와 일치해야 한다. PNG 끝점 평가와 MP4의 마지막 프레임은 서로 다른 개념이므로 마지막 화면 확인 근거를 구분한다.
+
+.blend의 실제 존재·SHA-256·Blender 버전·재열기·오브젝트/컬렉션·Scene 이름 검증은 PNG/MP4 디코딩·해상도·길이·상태 검증과 별개다. 설치 정보만으로 verified=true를 기록하지 않는다. 실패·부분 결과를 보존하고 필요한 단계로 돌아간다. 실제 최종 영상의 전체 재생·청취가 없으면 검수 해당 영역은 not_checked다.
+
+[계약 회귀 검사](../contracts/check.py)는 1.0/1.1 구조와 일부 참조·완료 조건을 검사한다. semantic_errors(data,context,complete=False)는 구조 검사 후 사용하며 context는 실제 사용 버전의 {stage_id:artifact}다. 1.0은 이 함수의 추가 의미 검사 대상이 아니다. 전체 파일·사용자 승인 진위·화면 품질 검증을 수행하지 않는다. 반환한 문제 목록이 비었어도 전체 단계 완료 증거를 대신하지 않는다.