feat: add versioned Blender production contracts

docs/architecture.md

@@ -1,13 +1,15 @@
 # 구성과 데이터 흐름
 
-ShortVideoGenerator는 개인용 Codex 작업 지침으로 구성된다. 서비스·데이터베이스·실행 프로그램이 아니라 역할 TOML, 작업별 SKILL.md, JSON 양식·스키마를 함께 사용하는 구조다.
+ShortVideoGenerator는 개인용 Codex 작업 지침으로 구성된다. 역할 TOML, 작업별 SKILL.md, JSON 양식·스키마를 함께 사용하고 승인된 로컬 실행 경로에 미디어 제작을 맡긴다. 서비스·데이터베이스는 두지 않는다.
 
 `.codex/agents/`의 8개 역할은 `.agents/skills/`의 담당 작업을 사용한다. 스킬은 `templates/`의 빈 양식과 `contracts/`의 전달 구조를 읽고, 제작별 `projects/<project_id>/`에 결과 버전과 사람용 검토를 남긴다. 총괄만 공유 진행 기록을 관리한다. 참고 자료는 이야기 구성·그림체의 입력이고 다른 제작의 상태·승인을 가져오는 저장소가 아니다.
 
 주제와 언어 요청은 총괄→주제·조사→작가→내레이션→장면→비주얼→영상·편집→검수 순으로 전달된다. 주제, 대본·제목, 장면, 완성본의 사용자 검토가 다음 구간을 연다. 검토를 기다리는 동안 경계를 넘는 새 후속 작업을 실행하지 않는다.
 
-음성 요청은 기존 conda qwen3-tts 환경의 Qwen3-TTS로, 기준·컷 이미지 요청은 gpt-image-2.5-sunburst로 전달하도록 지정했다. 실제 요청 실행 프로그램은 아직 없다. 모델·화자·지원 언어·결과 파일은 실제 제작 환경에서 확인해야 하며 설치 여부가 추론 성공을 뜻하지 않는다.
+음성 요청은 기존 conda qwen3-tts 환경의 Qwen3-TTS로, 새 모델·기준·컷 이미지·영상 요청은 Blender로 전달한다. 기존 1.0 이미지 모델 계약과 실제 결과는 보존하고 새 1.1과 함께 읽는다. 모델·화자·지원 언어·결과 파일은 실제 제작 환경에서 확인해야 하며 설치 여부가 추론 성공을 뜻하지 않는다.
 
-영상·합성 경계에는 시작/끝 이미지·움직임·컷 길이 또는 클립·음성·자막의 요청과 실제 결과 파일 정보가 오간다. 엔진·API 파라미터·인증정보는 전달 계약에 고정하지 않는다. 외부 결과가 없으면 진행이 멈추며 예상이나 모의 데이터를 실제 결과로 승격하지 않는다.
+영상·합성 경계에는 시작/끝 이미지·움직임·컷 길이 또는 클립·음성·자막의 요청과 실제 결과 파일 정보가 오간다. 1.1은 Blender의 .blend 원본·RenderProfile·Scene 이름·논리 프레임을 명시하고 PNG·MP4 결과를 별도로 기록한다. 합성은 승인된 기존 Remotion + FFmpeg 경로를 재사용한다. 실행파일의 외부 경로·인증정보는 전달 계약에 기록하지 않는다. 외부 결과가 없으면 진행이 멈추며 예상이나 모의 데이터를 실제 결과로 승격하지 않는다.
 
 대표적인 재개 요청은 기존 입력·포인터·승인·파일을 읽고 가장 앞선 미해결 단계에 배정된다. 결과가 갱신되면 실제 inputs 관계로 종속 결과를 다시 확인한다. 제목만 수정한 경우 새 제목은 합성과 검수에 전달되며 기존 음성·이미지는 유지된다.
+
+08의 제한된 대표 화면·짧은 움직임 제작만 scenes 승인 전 품질 검토를 위해 허용한다. 이 자료는 정식 10–12 완료가 아니다. 새 08·09의 scenes 승인 후 전체 모델·끝점·클립을 제작한다. 주제별 모델·장면은 해당 제작의 근거로 작성하며 다른 주제의 3D 자산을 자동 생성한다고 보장하지 않는다.

docs/business-rules.md

@@ -12,7 +12,7 @@
 
 장면은 각 컷의 시작·끝·카메라를 정하고 인접 컷의 이어짐 또는 전환 이유를 기록한다. 이어지는 컷은 인물·배경·행동·카메라 상태가 맞아야 한다. 반복 인물·배경의 고정 특징은 유지하고 이야기상 변화는 명시한다. 모든 영상의 고정 인물로 승격하지 않는다.
 
-이미지는 사용자 기준의 그림체를 따르며 캠핑 소재·상표를 의무로 복제하지 않는다. 각 컷에 start/end가 하나씩 필요하다. 같은 실제 이미지를 재사용해도 두 위치의 참조 기록은 남긴다. 영상은 그 사이의 설명에 필요한 움직임을 표현한다.
+새 시각 제작은 Blender 교육용 3D이며 사용자 원본의 단순 형태·정돈된 색을 참고한다. 단순 배경·부드러운 조명·선명한 형태를 사용하고 평면 스타일·캠핑 소재·상표를 의무로 복제하지 않는다. 각 컷에 start/end가 하나씩 필요하다. 같은 Scene의 continuous 경계에서 실제 PNG를 공유해도 두 위치의 별도 ID를 남긴다. cut 전환은 Scene 이름을 구분하며 같은 프레임 번호를 같은 상태로 취급하지 않는다. 영상은 그 사이의 설명에 필요한 움직임을 표현한다.
 
 결과 파일은 실제 존재·형식·메타데이터를 확인해야 한다. 요청·예상·설명용 예제는 검증 결과가 아니다. 파일 부재·부분 결과는 기다리는 상태이고 전체 완료로 처리할 수 없다. 설치 확인만으로 모델 로딩·추론을 확인했다고 쓰지 않는다.
 

docs/contracts.md

@@ -4,7 +4,7 @@
 
 ## 공통 출력
 
-진행 기록은 schema_version="1.0", project_id, brief={topic,language}, settings, stages, reviews다. stages의 항목은 {stage_id,status,revision,artifact_path,issues}, issues는 {code,message,blocking}다. reviews의 항목은 {review_id,decision,artifact_refs,feedback}이며 artifact_refs는 {stage_id,revision} 배열이다.
+진행 기록은 schema_version="1.1"(새 제작) 또는 "1.0"(기존 결과), project_id, brief={topic,language}, settings, stages, reviews다. stages의 항목은 {stage_id,status,revision,artifact_path,issues}, issues는 {code,message,blocking}다. reviews의 항목은 {review_id,decision,artifact_refs,feedback}이며 artifact_refs는 {stage_id,revision} 배열이다.
 
 단계 출력은 {schema_version,project_id,stage_id,revision,inputs,payload}다. revision은 1부터 시작하고 inputs는 실제 사용한 선행 버전 배열이다. project_id는 유일한 소문자 영숫자·하이픈이고, 경로는 저장소 루트 기준 상대 경로다. 이전 결과는 보존하며 review.md는 같은 JSON을 사람이 읽는 요약이다. 공통·단계별 필드 타입은 [진행 스키마](../contracts/project.schema.json)와 [단계 스키마](../contracts/artifact.schema.json), 시작 형태는 [양식](../templates/)에 있다.
 
@@ -15,16 +15,27 @@
 | 단계 | 요청 | 결과 |
 |---|---|---|
 | 06 | engine, conda_env, language, units | engine, model, voice, files, narration, unit_ranges |
-| 10 | model, style_reference, items | items |
-| 11 | model, frames | frames |
-| 12 | clips | clips |
+| 10 (1.1) | engine, style_reference, render_profile, items | scene_file, items |
+| 11 (1.1) | engine, scene_path, render_profile, frames | scene_file, frames |
+| 12 (1.1) | engine, scene_path, render_profile, clips | clips |
 | 13 | timeline, narration_path, captions, title | video, captions_path |
 
 06 units는 {id,block_ids,display_text,spoken_text,pronunciation_notes}, files는 {unit_id,media}, narration은 media, unit_ranges는 {unit_id,start_ms,end_ms}다. 요청 engine은 Qwen3-TTS, conda_env는 qwen3-tts이며 model·voice는 실제 사용값을 결과에 기록한다.
 
-10 요청 items는 {id,kind,entity_id,prompt}, 결과 items는 {reference_id,media}다. kind는 style/character/background이며 스타일만 entity_id=null이다. model은 gpt-image-2.5-sunburst, style_reference는 references/1.png다. 11 요청 frames는 {id,cut_id,position,prompt,reference_ids}, 결과 frames는 {frame_id,media}다. position은 start/end이고 컷마다 둘 다 하나씩 필요하다.
+1.0의 기존 이미지 모델 요청·결과 정의는 그대로 읽고 검증한다. 기존 제작·r1 미디어를 변환하거나 덮어쓰지 않는다. 새 1.1 프로젝트의 settings는 기존 aspect_ratio/max_duration_ms/max_cut_duration_ms/style_reference/tts_engine/conda_env 상수를 유지하고 image_model 대신 visual_engine="Blender"를 갖는다. 1.1 프로젝트의 inputs·포인터는 유효한 기존 1.0 결과를 참조할 수 있다.
 
-12 요청 clips는 {cut_id,start_frame_id,end_frame_id,duration_ms,motion_prompt}, 결과 clips는 {cut_id,media}다. 13 timeline은 {cut_id,video_path,start_ms,end_ms}, captions는 {id,start_ms,end_ms,text} 배열이다. video는 media이고 captions_path는 실제 SRT 경로다. 특정 영상·합성 엔진이나 API 파라미터는 계약에 고정하지 않는다.
+1.1의 08/10/11/12 외 payload는 1.0과 동일하다. 새 객체의 모든 명시된 키는 필수이고 추가 키를 허용하지 않는다.
+
+- BlendFile={path,verified,sha256,blender_version}. path는 루트 상대 문자열, verified는 불리언, sha256은 null 또는 소문자 64자리 16진수, blender_version은 null 또는 비어 있지 않은 문자열이다. verified=true이면 비어 있지 않은 경로·해시·버전이 모두 필요하다. 실제 파일 해시·재열기·버전을 확인하고 기록한다. .blend를 PNG/MP4 media로 기록하지 않는다.
+- RenderProfile={engine,device,fps,width,height,samples,seed}. engine은 BLENDER_EEVEE/CYCLES, device는 CPU/GPU, EEVEE는 GPU다. fps/width/height/samples는 양의 정수, seed는 0 이상 정수다. 의미 검사에서 9:16을 확인한다. 값은 렌더 요청이며 실제 지원·성공을 뜻하지 않는다.
+- 08 payload={scenes,connections,preview}. scenes/connections는 기존 구조다. preview는 null 또는 {scene_file:BlendFile,render_profile:RenderProfile,samples}이고 sample={id,cut_ids,media}다. id는 비어 있지 않고 유일하며 cut_ids는 비어 있지 않은 유일한 기존 컷 ID 배열, media는 실제 PNG 또는 MP4다. 대표 샘플은 scenes 검토 근거로만 사용한다.
+- 10 request={engine:"Blender",style_reference:"references/1.png",render_profile,items}. item={id,kind,entity_id,prompt}이며 kind는 style/character/background/object, style/object는 entity_id=null, character/background는 실제 09의 해당 ID를 참조한다. result는 null 또는 {scene_file:BlendFile,items}; 결과 item={reference_id,object_name,media:image}. reference_id는 요청 ID, object_name은 비어 있지 않은 실제 .blend 오브젝트/컬렉션 이름이다. 기준 PNG와 실제 자산을 함께 대조한다.
+- 11 request={engine:"Blender",scene_path,render_profile,frames}. scene_path는 생성할 원본의 루트 상대 경로다. frame={id,cut_id,position,prompt,reference_ids,scene_name,frame_index}; position은 start/end, scene_name은 비어 있지 않은 실제 Scene 이름, frame_index는 0 이상 논리 프레임이다. 같은 컷의 start/end는 같은 Scene을 사용한다. result는 null 또는 {scene_file:BlendFile,frames}; 결과 frame={frame_id,media:image}다.
+- 12 request={engine:"Blender",scene_path,render_profile,clips}. scene_path는 11의 검증된 실제 .blend 경로이고 render_profile은 11과 동일하다. clip={cut_id,start_frame_id,end_frame_id,duration_ms,motion_prompt,scene_name,start_frame,end_frame}. scene_name과 끝점 참조는 실제 11의 같은 Scene과 일치하고 start_frame/end_frame은 0 이상이며 end_frame>start_frame이다. duration_ms는 미작성 시 null, 작성 시 0 초과 5000 이하 정수이며 실측 07 구간과 같아야 한다. result는 기존 null 또는 {clips:[{cut_id,media:video}]}다.
+
+13/14의 구조는 바꾸지 않는다. 13 timeline={cut_id,video_path,start_ms,end_ms}, captions=[{id,start_ms,end_ms,text}], video는 media, captions_path는 실제 SRT 경로다. 합성은 기존 Remotion + FFmpeg 경로를 사용하며 실행파일의 외부 절대 경로·인증정보는 JSON에 담지 않는다.
+
+continuous는 같은 Scene의 앞 end와 뒤 start PNG를 공유할 수 있으나 위치별 ID는 별도다. cut은 서로 다른 Scene의 같은 frame_index를 구별하며 캐시 식별에는 Scene 이름이 필요하다. 프레임 구간은 [start_frame,end_frame)이다. 이번 물 영상은 50fps·5528개 프레임으로 시간 기준을 유지하고 마지막 끝점 PNG는 논리 프레임 5528을 평가한다. Blender의 실제 번호는 논리 프레임+1이다. 타 주제의 fps·길이를 이 값으로 고정하지 않는다.
 
 media는 {path,kind,verified,duration_ms,width,height}다. kind는 audio/image/video, 미확인 값은 null, verified는 불리언이다. 검증된 음성은 WAV·길이·width/height=null, 이미지는 PNG·크기·duration_ms=null, 영상은 MP4·길이·크기가 필요하다. 시간은 ms 정수이며 완료한 길이는 양수다. 결과의 ID는 요청에 존재해야 한다.
 

docs/operations.md

@@ -12,7 +12,7 @@ $short-video-workflow
 
 주제·각도 검토를 먼저 마치고 대본·제목, 실측 장면, 실제 완성본 검토 순으로 진행한다. 재개는 같은 스킬에 기존 제작 ID 또는 기록 위치를 전달한다. 전체 스킬 대신 개별 스킬을 불러도 필요한 선행 결과·승인은 유지한다.
 
-요청서를 실행하는 프로그램은 현재 제공하지 않는다. 실제 음성은 기존 qwen3-tts conda 환경에서 생성·확인한 WAV와 통합 단위 구간을 제출하고, 이미지는 지정 모델의 PNG와 요청 ID를 연결해 제출한다. 영상·합성 결과도 MP4·SRT와 실측 정보를 제출한다. 파일 부재·지원하지 않는 언어·시간 불일치는 문제를 보고하고 결과를 기다린다.
+새 시각 제작은 승인된 저장소 내 Blender 실행 경로를 사용한다. 실행 구성이 추가되어도 설치·요청 준비와 실제 출력 성공은 구분한다. 실제 음성은 기존 qwen3-tts conda 환경에서 생성·확인한 WAV와 통합 단위 구간을 제출하고, 새 모델·이미지는 Blender .blend 원본(해시·버전)과 실제 PNG·요청 ID·Scene·논리 프레임을 연결해 제출한다. 기존 1.0 결과는 그대로 읽는다. 영상·합성 결과도 MP4·SRT와 실측 정보를 제출한다. 파일 부재·지원하지 않는 언어·시간 불일치는 문제를 보고하고 결과를 기다린다.
 
 ## 파일 형식 검사
 
@@ -31,10 +31,12 @@ for name in ['project','artifact']:
     schema=json.loads(Path('contracts/'+name+'.schema.json').read_text(encoding='utf-8'))
     Draft202012Validator.check_schema(schema)
     validators[name]=Draft202012Validator(schema,format_checker=FormatChecker())
-for folder in ['templates','examples']:
+for folder in ['templates','examples','projects']:
     for path in Path(folder).rglob('*.json'):
+        if 'node_modules' in path.parts or '.cache' in path.parts:
+            continue
         data=json.loads(path.read_text(encoding='utf-8'))
-        if path.name=='verification-cases.json':
+        if not isinstance(data,dict) or 'schema_version' not in data or 'project_id' not in data:
             continue
         validators['artifact' if 'stage_id' in data else 'project'].validate(data)
 agents=list(Path('.codex/agents').glob('*.toml'))
@@ -67,6 +69,17 @@ Get-ChildItem -LiteralPath '.agents/skills' -Directory | ForEach-Object {
 
 ## 실제 제작 확인
 
-06의 통합 WAV를 먼저 확인한 뒤 07 시간을 정한다. 글자 수 추정으로 컷·자막을 실측처럼 확정하지 않는다. 08·09 사용자 승인 뒤 기준·컷 이미지로 진행한다. 모든 클립을 받은 뒤 합성 요청을 완성하고 실제 MP4·SRT의 시간·언어·화면을 확인한다.
+06의 통합 WAV를 먼저 확인한 뒤 07 시간을 정한다. 글자 수 추정으로 컷·자막을 실측처럼 확정하지 않는다. 08의 실제 대표 화면·짧은 움직임을 기존 scenes 검토에서 07/08/09와 함께 확인한다. 새 08·09 승인 뒤 정식 10 모델·기준 이미지, 11 끝점 PNG, 12 전체 컷 영상으로 진행한다. 모든 클립을 받은 뒤 합성 요청을 완성하고 실제 MP4·SRT의 시간·언어·화면을 확인한다.
 
 파일·메타데이터가 없는 외부 결과는 result=null, 부분 결과는 미완료다. 실제 최종 영상이 없으면 검수 결과는 incomplete이며 사용자 승인 없이는 완료를 선언하지 않는다. 서비스 실행·배포·업로드 명령은 현재 구성에 없다.
+
+## 1.0/1.1 계약 회귀 검사
+
+기존 환경에 jsonschema가 있으면 재설치하지 않고 다음 명령을 실행한다. 위 형식 검사와 함께 사용하며 실제 렌더링·청취·사용자 승인을 검사했다고 해석하지 않는다.
+
+```powershell
+python -X utf8 contracts/check.py
+if ($LASTEXITCODE -ne 0) { throw '계약 회귀 검사 실패' }
+```
+
+검사는 기존 1.0 예제·실제 제작 JSON, 새 1.1 빈 양식, 잘못된 버전·엔진·추가 키·검증 원본의 해시/버전 누락·프로필·시간을 다룬다. 의미 사례는 .blend의 media 위장, ID 중복·미존재 참조·Scene 불일치·9:16·루트 상대 경로·result=null 완료 금지를 다룬다. 전체 원본·미디어·승인·화면의 실제 검증은 각 단계의 실행 경로와 검토 근거로 확인한다. [1.1 연결 예제](../examples/blender-contract/README.md)는 실제 파일이 없는 요청 예제다.

docs/short-video-guide.md

@@ -98,11 +98,11 @@ Qwen3-TTS용 분할은 의미·호흡·발음 기준으로 한다. 긴 문장은
 
 ## 깔끔한 그림체로 작동 방식을 보여준다
 
-스타일은 [사용자 기준 이미지](../references/1.png)의 단순한 형태, 가는 윤곽선, 정돈된 색면과 제한적인 음영을 따른다. 참고 Shorts의 입체 렌더링이나 캠핑 소재를 이번 영상의 필수 스타일·배경으로 가져오지 않는다.
+새 제작은 Blender의 깔끔한 교육용 3D다. [사용자 기준 이미지](../references/1.png)는 보존하고 단순 형태·정돈된 색을 참고한다. 단순 배경, 부드러운 조명, 선명한 분자·물방울 등 주요 형태로 설명하며 평면 복제·캠핑 소재·상표를 강제하지 않는다. scenes 검토에서 실제 대표 화면·짧은 움직임을 먼저 확인하고 승인한 품질 기준으로 전체 제작한다.
 
-gpt-image-2.5-sunburst 요청에는 조사 근거, 대본, 장면 상태, 반복 인물·배경의 고정 특징을 연결한다. 복잡한 메커니즘은 시각 요소를 줄여 설명하되 자연 퇴적물과 콘크리트 시설, 그늘과 냉방처럼 사실에 중요한 차이는 남긴다. 추측한 구조를 사실을 설명하는 도해로 사용하지 않는다.
+Blender 모델·장면·애니메이션 요청에는 조사 근거, 대본, 장면 상태, 반복 인물·배경의 고정 특징을 연결한다. 복잡한 메커니즘은 시각 요소를 줄여 설명하되 자연 퇴적물과 콘크리트 시설, 그늘과 냉방처럼 사실에 중요한 차이는 남긴다. 추측한 구조를 사실을 설명하는 도해로 사용하지 않는다.
 
-컷 하나에서는 주요 물체와 변화가 먼저 보이게 한다. 강조 색·화살표·라벨이 서로 다른 대상을 동시에 가리키지 않게 하고, 같은 요소의 색과 기호는 일관되게 사용한다. 생성 이미지의 글자·숫자가 정확하지 않으면 이미지에 억지로 남기지 않고 합성 단계에서 검증한 텍스트로 배치한다.
+컷 하나에서는 주요 물체와 변화가 먼저 보이게 한다. 강조 색·화살표·라벨이 서로 다른 대상을 동시에 가리키지 않게 하고, 같은 요소의 색과 기호는 일관되게 사용한다. 설명 글자·숫자는 3D 표면에 억지로 남기지 않고 합성 단계에서 검증한 텍스트로 배치한다.
 
 움직임은 물높이 변화·부품 조작·그림자 이동 등 설명에 필요한 상태 변화를 우선한다. 줌·흔들림·장식적 움직임을 설명의 대체물로 쓰지 않는다. 시작·끝 프레임과 움직임 요청은 같은 상태 변화를 설명해야 한다.
 
@@ -123,7 +123,7 @@ gpt-image-2.5-sunburst 요청에는 조사 근거, 대본, 장면 상태, 반복
 | 03–04 대본·제목 | 이야기 작가 | 질문부터 답까지의 구성, 쉬운 말, 약속과 회수 |
 | 05–06 분할·음성 | 내레이션 담당 | 의미·호흡·발음, 요청과 실제 음성의 구분 |
 | 07–09 컷·연결·반복 요소 | 장면 감독 | 실제 시간, 화면 역할, 상태 변화와 연속 기준 |
-| 10–11 기준·컷 이미지 | 비주얼 담당 | 첨부 그림체, 구조의 정확성, 고정 특징·글자 확인 |
+| 10–11 기준·컷 이미지 | 비주얼 담당 | 교육용 3D 모델·.blend 원본, 구조의 정확성, 고정 특징·끝점 확인 |
 | 12–13 영상·합성 | 영상·편집 담당 | 설명에 필요한 움직임, 자막·주석, 모바일 판독성 |
 | 14 최종 검수 | 최종 검수자 | 도입의 약속부터 완성본까지 근거로 확인 |
 | 전체 | 제작 총괄 | 지침 적용 요약과 네 사용자 검토의 연결 |

docs/standards.md

@@ -10,7 +10,7 @@
 
 실제 완료는 구조 검사 외에 선행 버전·선택 ID·주장 출처·배열 식별자·파일·실측·사용자 승인을 확인해야 한다. request만 있거나 verified=false 미디어를 필수 결과로 쓰는 완료 처리는 오류다. 미검수 영역을 pass로 기록하는 것도 오류다.
 
-공통 설정은 주제·언어 입력, 세로 9:16, 전체 180000ms 이내, 각 컷 0ms 초과 5000ms 이하, 사용자 그림체, Qwen3-TTS 기존 환경과 gpt-image-2.5-sunburst다. 실제 지원 여부는 제작 환경에서 확인하며 확인하지 않은 API 파라미터를 고정하지 않는다.
+공통 설정은 주제·언어 입력, 세로 9:16, 전체 180000ms 이내, 각 컷 0ms 초과 5000ms 이하, 사용자 원본의 단순 형태·정돈된 색을 해석한 교육용 3D, Qwen3-TTS 기존 환경과 Blender다. 1.1은 visual_engine=Blender이며 기존 1.0과 지정 이미지 모델 기록은 보존한다. .blend는 media와 구분해 경로·검증 상태·SHA-256·Blender 버전을 기록한다. 실제 지원 여부는 제작 환경에서 확인하며 확인하지 않은 API 파라미터를 고정하지 않는다.
 
 가정·중요한 미확정 의도를 먼저 밝히고 필요한 최소 변경을 한다. 관련 없는 코드·주석·서식·기존 불필요한 코드를 정리하지 않는다. 이번 변경이 새로 불필요하게 만든 항목만 제거한다. 동작을 바꾸는 변경은 해당 성공·실패 조건을 실제로 검증하고, 문서·양식은 형식·참조·예제 흐름을 확인한다.
 

docs/workflow-contracts.md

@@ -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은 이 함수의 추가 의미 검사 대상이 아니다. 전체 파일·사용자 승인 진위·화면 품질 검증을 수행하지 않는다. 반환한 문제 목록이 비었어도 전체 단계 완료 증거를 대신하지 않는다.