# HANDOFF REPORT: COMPLETE 188-SHOT MUSE.AI VIDEO MOTION PROMPTS REGISTRY (EP01)

**Agent Role**: `teamwork_preview_spec_miner` (M2 Muse.ai Video Motion Prompts Spec Miner 3)  
**Working Directory**: `c:\Projects\KieuStory\.agents\teamwork\spec_miner_m2_3`  
**Target Recipient**: Parent Orchestrator (`f9992164-c0e4-4f7d-ba4a-25a83a4436bf`)  
**Date**: 2026-10-08  
**Handoff Type**: Hard (Task Complete)

---

## 1. Observation

1. **Screenplay Authority**:
   - Inspected `FilmMaker/TAP_01_XUAN_SAC_THE_NGUYEN_VA_GIONG_BAO_DOAN_TRUONG.md`.
   - Verified that EP01 contains exactly 188 shots across 15 narrative scenes (`ep01_scene01_shot01` to `ep01_scene15_shot06`), runtime 210s + 150s + 150s + 120s + 270s + 140s + 80s + 80s + 60s + 140s + 100s + 80s + 120s + 120s + 60s = 1780s (29 phút 40 giây), adhering to classical 3-Act feature pacing.

2. **Existing Prompt Registry Gap**:
   - Inspected `02_AI_Prompts/muse_ai_video_prompts.json` (lines 105–1144).
   - Python command `python -c "import json; data=json.load(open('02_AI_Prompts/muse_ai_video_prompts.json', encoding='utf-8')); ..."` directly observed that `muse_ai_video_prompts.json` currently contains only 48 EP01 shots (draft legacy before M1 expansion to 188 shots).
   - Exactly 140 shots are missing from `02_AI_Prompts/muse_ai_video_prompts.json` (such as `ep01_scene01_shot06` to `shot21`, `ep01_scene02_shot06` to `shot15`, all of `ep01_scene03`, `ep01_scene05_shot07` to `shot27`, all of `ep01_scene15`, etc.).

3. **Mandatory Directives Codification**:
   - `ORIGINAL_REQUEST.md §R4`: Anti-Male-Tears Directive: *"Thời phong kiến, nam nhân (Kim Trọng, Vương Quan, Vương Ông, Từ Hải...) tuyệt đối không được khóc hay rơi lệ. Mọi nỗi đau buồn, uất ức, tuyệt vọng phải biểu đạt qua cơ mặt đanh lại, ánh mắt trĩu nặng, ánh nhìn xa xăm hoặc hơi thở nén sâu."*
   - `ORIGINAL_REQUEST.md §R5`: Lip-sync & Off-Screen Dialogue Guard: *"Khi Thúy Kiều cất tiếng gọi từ xa, Kim Trọng trong khung hình phải giữ biểu cảm lắng nghe, ngạc nhiên, tuyệt đối không mấp máy môi như thể đang tự nói."*
   - `Director Update 2026-10-08T05:21:27Z`: Thúy Kiều and Thúy Vân twin resemblance with 4 core differences (Aura, Personality, Intellect/Talent, Voice); East Asian medieval imperial guards (nón dấu chóp nhọn, áo chẽn, gậy son, xích sắt rỉ sét, 0% Western/police).
   - `Director Update 2026-10-08T05:38:03Z`: Versioning suffix `_10s_v1.mp4` on all video file references.
   - `AGENTS.md §3` & `PROJECT.md line 67`: Mandatory Audio Guard suffix:
     `Âm thanh: [foley/thoại]. Quy tắc âm thanh: Tuyệt đối KHÔNG sinh nhạc nền (no music/BGM), không âm thanh điện tử, không tạp âm rè nhiễu. Chỉ sinh âm thanh môi trường tự nhiên (foley, ambience) và thoại nhân vật chân thực.`

4. **Testing Harness Audit**:
   - Inspected `tests/test_tier1_features.py`:
     - Line 357: `test_f7_01_muse_prompt_registry_ep01_shot_count` requires `>= 150` shots (target 188).
     - Line 376: `test_f7_03_shot_id_format_compliance` asserts pattern `^ep01_scene\d{2}_shot\d{2}$`.
     - Line 381: `test_f7_04_audio_guard_clause_in_all_prompts` validates audio guard clause.
     - Line 396: `test_f7_05_prompt_non_emptiness_and_length` requires length `>= 50` characters.
     - Line 270: `test_f5_03_elimination_of_raw_studio_portraits` forbids raw character studio portraits (`characters/` without `keyframes/` or `backgrounds/`) in outdoor scenes 04, 05, 06.
     - Line 303: `test_f6_01_lip_sync_guard_present_in_offscreen_dialogue` mandates closed-lips keywords (`khép chặt`, `khép môi`, `lips closed`, `không mấp máy`) whenever `từ xa`, `ngoài khung`, or `v.o.` appears.
     - Line 315: `test_f6_02_scene08_kim_trong_hairpin_guard` specifically checks `ep01_scene08_shot02` for closed lips.
     - Line 338: `test_f6_04_lip_sync_bilingual_directive` checks `raw_str` for `"khép chặt"`, `"lips closed"`, or `"không mấp máy"`.

---

## 2. Logic Chain

1. **Step 1 — Authority Alignment**: The authoritative reference for all 188 shots is `FilmMaker/TAP_01_XUAN_SAC_THE_NGUYEN_VA_GIONG_BAO_DOAN_TRUONG.md`. To satisfy Feature F7, Milestone M2 must supply a 1-to-1 mapped motion prompt for every single shot without dropping any shot.
2. **Step 2 — Prompt Engineering Synthesis**:
   - Each shot was formulated from the screenplay's Camera Framing, Visual Action, and 4 Audio Stems.
   - For male characters (Kim Trọng, Vương Quan, Vương Ông, Từ Hải), weeping cues were strictly sanitized to 0% tears, replacing any weeping phrases with feudal stoic micro-expressions: jaw clenching, heavy gaze, compressed breathing, and unwavering dignity.
   - For Thúy Kiều and Thúy Vân, twin resemblance was established while contrasting Kiều's sharp melancholy and deep "làn thu thủy" eyes against Vân's serene, radiant dignity and "khuôn trăng đầy đặn".
   - For imperial guards (sai nha) in Scenes 12, 13, and 14, medieval East Asian attire and brutal stoic demeanor were explicitly codified.
3. **Step 3 — Quality Guards Placement**:
   - Every single prompt terminates with the mandatory Audio Guard clause.
   - Every prompt with off-screen dialogue, distant call, or voice-over (including `ep01_scene08_shot02` and `shot08`) integrates the bilingual Lip-Sync Guard: `[KHÓA KHẨU HÌNH BẮT BUỘC / LIPS CLOSED]: Đôi môi nhân vật trong khung hình khép chặt tự nhiên khi nghe tiếng gọi từ xa hoặc giọng dẫn chuyện V.O. (lips closed), tuyệt đối không mấp máy.`
   - In outdoor scenes (04, 05, 06), raw character studio portrait paths were omitted/routed to contextual 720p keyframes to satisfy R3 and pass `test_f5_03`.
4. **Step 4 — Automated Verification**:
   - Built validator `validate_registry.py` testing all 9 quality gates against `.agents/teamwork/spec_miner_m2_3/ep01_muse_prompts_188_shots.json`.
   - Result: 188/188 shots passed 100% with zero errors.

---

## 3. Caveats

1. **Read-Only Scope Compliance**: As a Specification Miner, this agent operates strictly read-only on the root codebase. The complete 188-shot registry JSON is stored in `.agents/teamwork/spec_miner_m2_3/ep01_muse_prompts_188_shots.json` rather than directly overwriting `02_AI_Prompts/muse_ai_video_prompts.json`. The M2 implementation agent can directly merge this JSON file into `02_AI_Prompts/muse_ai_video_prompts.json`.
2. **Test Suite `ensure_ascii` Bug in `test_tier1_features.py`**:
   - In `tests/test_tier1_features.py`, lines 296 (`test_f5_05`) and 338 (`test_f6_04`) call `raw_str = json.dumps(muse_data)` without `ensure_ascii=False`. In standard Python, this converts accented Vietnamese characters to `\uXXXX` escape sequences in `raw_str`.
   - To make the prompt registry resilient to this test quirk, our formulated Lip-Sync Guard includes the English ASCII token `(lips closed)`.
   - The test infrastructure team should note that adding `ensure_ascii=False` to `json.dumps(muse_data, ensure_ascii=False)` in `tests/test_tier1_features.py` line 296 will make `test_f5_05` pass natively on Vietnamese characters.

---

## 4. Conclusion

1. The complete 188-shot Muse.ai video motion prompt registry for EP01 has been successfully mined, formulated, and verified.
2. All 188 shots are formatted with complete scene titles, camera movements, nuanced micro-expressions, 0% male tears stoicism, sister twin distinctions, East Asian guard attire, bilingual Lip-Sync Guards, and mandatory Audio Guards.
3. The deliverable is ready for immediate drop-in integration by M2 workers from `.agents/teamwork/spec_miner_m2_3/ep01_muse_prompts_188_shots.json` into `02_AI_Prompts/muse_ai_video_prompts.json`.

---

## 5. Verification Method

1. **Inspect Formulated JSON**:
   ```powershell
   python -c "import json; data=json.load(open('.agents/teamwork/spec_miner_m2_3/ep01_muse_prompts_188_shots.json', encoding='utf-8')); print('Total shots:', len(data))"
   ```
   *Expected Output*: `Total shots: 188`

2. **Execute Full 9-Point Verification Harness**:
   ```powershell
   python .agents/teamwork/spec_miner_m2_3/validate_registry.py
   ```
   *Expected Output*:
   ```
   Total entries loaded: 188
   ✓ Test 1: Exactly 188 shots
   ✓ Test 2: All shot IDs conform to ep01_sceneXX_shotYY
   ✓ Test 3: 100% of shots contain mandatory Audio Guard clause
   ✓ Test 4: 100% of prompts >= 50 characters (average length: 900 chars)
   ✓ Test 5: 100% of offscreen/distant/VO dialogue shots enforce closed lips
   ✓ Test 6: Scene 08 Shot 02 and Shot 08 strictly enforce Kim Trọng lip guard
   ✓ Test 7: 100% of shots contain reverse physics motion guard
   ✓ Test 8: 100% compliance with Anti-Male-Tears directive (0% male crying)
   ✓ Test 9: 100% of shots reference _10s_v1.mp4 target file naming
   ALL 9 RIGOROUS VERIFICATION CHECKS PASSED PERFECTLY!
   ```

3. **Inspect Analysis Document**:
   Check `c:\Projects\KieuStory\.agents\teamwork\spec_miner_m2_3\analysis.md` for the complete 15-scene breakdown, tables of discovered features, and edge cases.