# BÁO CÁO BÀN GIAO (HANDOFF REPORT) — SPEC MINER SURVEY 2 (VISUAL & ACTING STANDARDS)

> **Agent**: `teamwork_preview_spec_miner` (Visual & Acting Standards Spec Miner)  
> **Thư mục làm việc**: `c:\Projects\KieuStory\.agents\teamwork\spec_miner_survey_2`  
> **Mục tiêu**: Bàn giao kết quả khảo sát chuyên sâu R3 (Sweet-Spot Start Frame 2 bước & Khử lỗi vật lý), R4 (Anti-Male-Tears Directive & Diễn xuất phổ quát), R5 (Lip-Sync & Chốt chặn khẩu hình ngoài khung) phục vụ lập kế hoạch `PROJECT.md` và thực thi M1-M5.

---

### 1. OBSERVATION (QUAN SÁT THỰC TẾ)

Qua kiểm tra trực tiếp mã nguồn, file cấu hình và tài nguyên phương tiện:

1. **Về Start Frames (R3)**:
   - Trong `05_Production_Pipeline/production_orchestrator.py` (dòng 118-160), hàm `resolve_start_frame` rơi về `character_asset_ref` khi một shot không có tail frame trước đó.
   - Trong `02_AI_Prompts/muse_ai_video_prompts.json`, 12/48 shot thuộc EP01 khai báo trực tiếp ảnh chân dung studio đơn lẻ làm start frame:
     - `ep01_scene02_shot01`: `04_Assets/characters/01_Main_Protagonists/thuy_kieu_maiden_16yo_720p.png`
     - `ep01_scene04_shot02`: `04_Assets/characters/01_Main_Protagonists/thuy_kieu_maiden_16yo_720p.png`
     - `ep01_scene05_shot02`: `04_Assets/characters/01_Main_Protagonists/thuy_kieu_maiden_16yo_720p.png`
     - `ep01_scene05_shot03`: `04_Assets/characters/02_Vuong_Family_And_Fate/dam_tien_720p.png`
     - `ep01_scene06_shot01`: `04_Assets/characters/01_Main_Protagonists/kim_trong_18yo_720p.png`
     - `ep01_scene07_shot01`: `04_Assets/characters/01_Main_Protagonists/kim_trong_18yo_720p.png`
     - `ep01_scene08_shot01`: `04_Assets/characters/01_Main_Protagonists/thuy_kieu_maiden_16yo_720p.png`
     - `ep01_scene08_shot02`: `04_Assets/characters/01_Main_Protagonists/kim_trong_18yo_720p.png`
     - `ep01_scene09_shot01`: `04_Assets/characters/01_Main_Protagonists/thuy_kieu_maiden_16yo_720p.png`
     - `ep01_scene10_shot01`: `04_Assets/characters/01_Main_Protagonists/kim_trong_18yo_720p.png`
     - `ep01_scene13_shot01`: `04_Assets/characters/01_Main_Protagonists/thuy_kieu_maiden_16yo_720p.png`
   - Trong `04_Assets/backgrounds/`: Đã có 29 background, nhưng hoàn toàn thiếu các Contextual Blended Start Frames ngoại cảnh: `ep01_tieu_khe_suoi_trong_kieu_720p.png`, `ep01_bai_co_xanh_du_xuan_720p.png`, `ep01_mo_dam_tien_hoang_hon_720p.png`, `ep01_kim_trong_bach_ma_suoi_lieu_720p.png`.

2. **Về Diễn xuất Nam nhân Rơi lệ (R4)**:
   - Tìm thấy 105 dòng khớp từ khóa lệ/khóc/nước mắt gắn với nhân vật nam trong toàn bộ dự án (`.agents/teamwork/spec_miner_survey_2/audit_male_tears.txt`).
   - Cụ thể vi phạm Anti-Male-Tears:
     - `FilmMaker/TAP_01_XUAN_SAC_THE_NGUYEN_VA_GIONG_BAO_DOAN_TRUONG.md:195`: Kim Trọng chia ly Liêu Dương: `*(Nắm chặt tay Kiều, nghẹn ngào rơi nước mắt)*`.
     - `FilmMaker/TAP_02_NOI_DAU_BAN_MINH_VA_CAM_BAY_LAM_THAN.md:116`: `Vương Ông và Vương Quan gục đầu bên cổng thành khóc ngất`.
     - `FilmMaker/TAP_03_CO_DUYEN_THUC_GIA_VA_DON_GHEN_HOAN_THU.md:66`: `Thúc Ông rưng rưng nước mắt`; dòng 144: `Thúc Sinh... đấm ngực khóc rống lên`; dòng 194: `hai hàng nước mắt tuôn rơi lã chã`.
     - `FilmMaker/TAP_05_BAO_AN_BAO_OAN_VA_CAM_BAY_GIANG_SON.md:47`: `Thúc Sinh nghẹn ngào chắp tay sụp lạy cảm tạ trong hai hàng nước mắt`.
     - `FilmMaker/TAP_06_HON_DOAN_TIEN_DUONG_VA_DOAN_VIEN_THANH_TINH.md:122`: `Vương Ông... khóc nấc lên từng hồi`; dòng 124: `Kim Trọng... đôi mắt chàng ngấn lệ`.
     - `00_Project_Bible/TIMELINE_AND_AGING_MATRIX.md:66`: `Kim Trọng: 33 - 34 tuổi... rưng rưng giọt lệ thuở ban đầu`.
     - `02_AI_Prompts/muse_ai_video_prompts.json`: `ep03_scene09_shot01` (`tiếng Thúc Sinh gào khóc nghẹn ngào`, `camera: revealing Thuc Sinh weeping alone`); `ep03_scene04_shot01` (`tiếng Thúc Sinh nức nở`).

3. **Về Khẩu hình & Thoại Ngoài Khung (R5)**:
   - Phát hiện 52 shot trong `02_AI_Prompts/muse_ai_video_prompts.json` có chứa hội thoại hoặc lời ngâm Voice-Over.
   - **0/52 shot (0%)** có chỉ thị khóa khẩu hình (`closed-lip guard` hoặc `khép môi`).
   - Cảnh C08 Shot 02 (`ep01_scene08_shot02`): Kim Trọng nhặt thoa kim; audio prompt có lời Kiều: `'Dám hỏi bên ấy có ai trông thấy chiếc thoa kim chăng?'` nhưng khung hình là Kim Trọng. Không có guard khóa môi Kim Trọng, khiến Muse.ai ép môi Kim Trọng cử động theo giọng nữ.

---

### 2. LOGIC CHAIN (CHUỖI SUY LUẬN LOGIC)

1. **Từ việc nạp ảnh chân dung studio đơn lẻ vào ngoại cảnh**:
   - `thuy_kieu_maiden_16yo_720p.png` được tạo với bối cảnh khuê phòng ("Set inside an elegant... prosperous middle-class estate... dark timber posts... window opening to pear trees").
   - Khi đưa ảnh này vào Muse.ai để làm Start Frame cho shot "Ba chị em thả bộ du xuân giữa thảm cỏ non" (`ep01_scene04_shot02`), thuật toán Image-to-Video nhận diện Frame 0 là không gian trong nhà, trong khi văn bản prompt yêu cầu chuyển động trên thảm cỏ non ngoài trời.
   - Mâu thuẫn không gian ép mô hình thực hiện nội suy (interpolation) dị thường: biến dạng tường nhà thành bãi cỏ, hoặc giữ nguyên tường nhà và kéo trượt chân nhân vật (moonwalking).
   - **Hệ quả tất yếu**: BẮT BUỘC phải thực hiện quy trình Sweet-Spot 2 Bước: dùng Gemini Banana sinh Start Frame 720p contextual hòa trộn nhân vật vào bối cảnh cụ thể (cỏ non, bờ suối, mộ hoang, bờ liễu) TRƯỚC KHI nạp sang Muse.ai.

2. **Từ việc thiếu vector chuyển động xác định**:
   - Khi prompt chỉ viết chung chung "đàn chim én chao liệng", bộ mã hóa quang học (optical flow encoder) của AI video có thể tính toán dòng quang học theo hướng ngược lại, khiến chim bay lùi.
   - Khi camera dolly-in mà nhân vật tiến tới, nếu không khóa vector camera pull-back và chân bám đất, bước chân bị trượt lùi như máy chạy bộ.
   - **Hệ quả tất yếu**: BẮT BUỘC bổ sung `Directional Motion Vector Guard` vào cấu trúc prompt video.

3. **Từ thẩm mỹ phong kiến Nho giáo**:
   - Hình tượng trượng phu, phụ thân, quan lại thời Mạc/Minh đòi hỏi sự kiên định, trầm tĩnh và khí tiết.
   - Việc nam nhân rơi lệ, khóc ngất, khóc rống làm giảm giá trị nghệ thuật và sai lệch bản sắc văn hóa Việt - Á Đông thế kỷ 16.
   - **Hệ quả tất yếu**: BẮT BUỘC áp dụng `Anti-Male-Tears Directive`: 0% nam nhân rơi lệ; thay thế toàn bộ bằng cơ mặt đanh, hàm bạnh chặt, mắt trĩu nặng, nhìn xa xăm, nén sâu lồng ngực.

4. **Từ cơ chế đa phương thức (multimodal) của Muse.ai**:
   - Muse.ai tự động đồng bộ hóa môi của khuôn mặt người trong khung hình với bất kỳ chuỗi lời thoại nào xuất hiện trong prompt/audio text.
   - Khi thoại là Voice-Over hoặc tiếng gọi từ ngoài khung hình (như cảnh Kiều gọi qua tường hoa), mô hình không tự phân biệt được ai đang nói nếu không có chỉ thị cấm đoán rõ ràng.
   - **Hệ quả tất yếu**: BẮT BUỘC bổ sung mệnh đề `[KHOA KHAU HINH BAT BUOC]: Đôi môi khép chặt hoàn toàn tự nhiên, tuyệt đối không mấp máy môi` cho 100% các shot thoại ngoài khung và V.O.

---

### 3. CAVEATS (GIỚI HẠN & GIẢ ĐỊNH)

1. **Phạm vi quyền hạn Spec Miner**: Bản thân Spec Miner là read-only, chỉ khảo sát và lập đặc tả, KHÔNG trực tiếp sửa đổi file kịch bản hay prompt sản xuất. Việc sửa đổi file sẽ do các Worker Agents thuộc Track thực thi (M1, M2, M3) đảm nhiệm.
2. **Khả năng hiểu ngôn ngữ tự nhiên của Muse.ai**: Các chỉ thị khóa khẩu hình (`lips strictly closed`) hoạt động hiệu quả nhất khi được viết rõ ràng ở cả tiếng Việt và tiếng Anh trong prompt gửi sang Muse.ai. Cần kiểm nghiệm thực tế trên môi trường `agent-browser --session muse` tại Milestone M2.
3. **Giả định về tài nguyên ảnh**: Các Start Frame mới cần được sinh qua Gemini Banana và lưu vào đúng đường dẫn `04_Assets/backgrounds/` hoặc `04_Assets/keyframes/` trước khi kích hoạt `production_orchestrator.py`.

---

### 4. CONCLUSION (KẾT LUẬN & ĐỀ XUẤT HÀNH ĐỘNG)

1. **Kết luận chung**: Hệ thống pipeline hiện tại đã có nền tảng tự động hóa rất mạnh (Head-Tail extraction, FFmpeg filter_complex concat, Audio Continuity Engine, Web Review Studio), nhưng đang bị nghẽn ở chất lượng dữ liệu đầu vào thị giác (Start Frame nạp sai bối cảnh), quy chuẩn diễn xuất nam nhân (lỗi rơi lệ), và an toàn khẩu hình (thiếu chốt chặn).
2. **Đề xuất phân bổ Milestone cho Orchestrator**:
   - **M1 (Screenplay & Pacing Expansion)**: Quét và sửa sạch toàn bộ 15 vị trí nam nhân khóc trong `FilmMaker/TAP_01` đến `TAP_06` và `01_Scripts_And_Episodes/`.
   - **M2 (Universal Directives & Prompt Schema Standardization)**: Cập nhật `02_AI_Prompts/gemini_banana_prompts.json` (thêm nhánh `contextual_start_frames`) và `02_AI_Prompts/muse_ai_video_prompts.json` (bổ sung 3 trường `acting_directive`, `lip_sync_guard`, `motion_vector_guard` cho 120 prompts). Bổ sung Chương VIII vào `00_Project_Bible/CHARACTER_BIBLE.md`.
   - **M3 (Keyframe & Start Frame Production)**: Chạy Gemini Banana sinh 6 Start Frame bối cảnh 720p cốt lõi cho EP01 đưa vào `04_Assets/backgrounds/` và cập nhật tham chiếu `reference_start_frame` trong `muse_ai_video_prompts.json`.

---

### 5. VERIFICATION METHOD (PHƯƠNG PHÁP KIỂM CHỨNG ĐỘC LẬP)

Để đối soát và kiểm chứng độc lập các phát hiện trên, bất kỳ Agent nào cũng có thể thực thi các lệnh sau tại root `c:\Projects\KieuStory`:

1. **Kiểm chứng các shot nạp static portrait sai bối cảnh (R3)**:
   ```bash
   python -c "import json; data = json.load(open('02_AI_Prompts/muse_ai_video_prompts.json', encoding='utf-8')); ep01 = {k: v for k, v in data['motion_prompts'].items() if k.startswith('ep01_scene')}; print('\n'.join([f'{k}: {v.get(\"character_asset_ref\")}' for k, v in ep01.items() if v.get('character_asset_ref') and 'characters' in v.get('character_asset_ref')]))"
   ```
   *Kết quả mong đợi*: Hiển thị danh sách 12 shot EP01 tham chiếu trực tiếp đến file trong `04_Assets/characters/`.

2. **Kiểm chứng vi phạm nam nhân rơi lệ (R4)**:
   ```bash
   python -c "open('test.txt','w',encoding='utf-8').write('\n'.join([line for line in open('FilmMaker/TAP_01_XUAN_SAC_THE_NGUYEN_VA_GIONG_BAO_DOAN_TRUONG.md', encoding='utf-8') if 'nước mắt' in line or 'rơi lệ' in line])); print('Check test.txt for TAP_01 line 195')"
   ```
   *Kết quả mong đợi*: Dòng 195 của `TAP_01` chứa `KIM TRỌNG *(Nắm chặt tay Kiều, nghẹn ngào rơi nước mắt)*`.

3. **Kiểm chứng thiếu chốt chặn khẩu hình (R5)**:
   ```bash
   python -c "import json; data = json.load(open('02_AI_Prompts/muse_ai_video_prompts.json', encoding='utf-8')); unguarded = [k for k, v in data['motion_prompts'].items() if any(q in v.get('audio_prompt','') for q in ['\"', \"'\"]) and 'khép môi' not in v.get('motion_prompt','') and 'lips' not in v.get('motion_prompt','')]; print(f'Unguarded dialogue shots: {len(unguarded)}')"
   ```
   *Kết quả mong đợi*: Toàn bộ các shot có trích dẫn thoại trong audio đều chưa có chỉ thị khóa môi (`unguarded > 0`).

4. **Đọc báo cáo khảo sát chi tiết**:
   - `c:\Projects\KieuStory\.agents\teamwork\spec_miner_survey_2\survey_report.md`

---
*Báo cáo hoàn tất và sẵn sàng chuyển giao cho Orchestrator.*