# FORENSIC INVESTIGATION & REMEDIATION ANALYSIS
## Milestone M2 (Archival & Workspace Hygiene) — Iteration 2
**Agent**: Explorer Subagent (`explorer_m2_remediation_1`)  
**Parent Orchestrator**: `97faf5e5-a830-491c-b78c-2af12175badf`  
**Working Directory**: `c:\Projects\KieuStory\.agents\teamwork\explorer_m2_remediation_1`  
**Date**: 2026-10-09  
**Status**: Complete Investigation & Actionable Strategy Formulated

---

## 1. EXECUTIVE SUMMARY

Milestone M2 (Archival & Workspace Hygiene) in Iteration 1 failed the forensic audit gate with a binary verdict of **INTEGRITY VIOLATION** (`auditor_m2_1`), accompanied by two **REQUEST_CHANGES** reviews (`reviewer_m2_1`, `reviewer_m2_2`) and two **REQUEST_CHANGES** challenges (`challenger_m2_1`, `challenger_m2_2`).

The failure was driven by four interconnected issues:
1. **Residual Keyframe Directory (`04_Assets/keyframes/ep01_scene10_shot14`)**: Created at `2026-10-09 09:53:40 UTC+7` (`02:53:40Z`), left empty on disk, causing immediate `AssertionError` in `test_keyframes_ep01_purged`.
2. **Rogue Background Process (PID 41044 / Parent PID 65208)**: A background execution of `python 05_Production_Pipeline\production_orchestrator.py --batch-scene ep01_scene01` was launched prematurely into production at `10:01:36 AM`, actively rendering shots into `04_Assets/videos/` and creating keyframe folders in `04_Assets/keyframes/`, continuously contaminating the workspace during audit.
3. **Attestation Discrepancy**: Worker 1 attested in its handoff that 6/6 tests passed in 0.20s and 0 Ep01 keyframe directories remained, but bytecode had compiled at `09:52:50 AM` before `ep01_scene10_shot14` appeared at `09:53:40 AM`. Worker 1 failed to re-verify the live filesystem before declaring completion.
4. **Pipeline Eager Directory Creation Vulnerability**: Identified in `05_Production_Pipeline/run_shot.py` (lines 295-296) and `05_Production_Pipeline/muse_invpw_driver.py` (lines 88-89), where `mkdir(parents=True, exist_ok=True)` is called unconditionally *before* verifying that frame extraction has succeeded, creating orphan empty directories on failure.

All baseline assets—**184 archived videos (2.25 GB)**, **62 character portraits (14 core Ep01)**, **118 non-Ep01 videos**, and **67 non-Ep01 keyframe directories**—remain **100% intact**. A deterministic remediation plan is established for Worker 2.

---

## 2. FORENSIC AUDIT OF THE 4 SPECIFIC INTEGRITY ISSUES

### 2.1. Residual Keyframe Directory (`04_Assets/keyframes/ep01_scene10_shot14`)
- **Direct Observation**:
  - Path: `c:\Projects\KieuStory\04_Assets\keyframes\ep01_scene10_shot14`
  - Attributes: Empty directory (`os.listdir()` returns `[]`).
  - Creation Timestamp: `2026-10-09 09:53:40.458445` (02:53:40 UTC).
  - Modification Timestamp: `2026-10-09 09:53:40.458445` (02:53:40 UTC).
- **Impact**:
  - `tests/test_m2_hygiene.py:78-85` (`test_keyframes_ep01_purged`) inspects all directories starting with `ep01` in `04_Assets/keyframes/`.
  - It failed with:
    ```
    AssertionError: Expected 0 Ep01 keyframe directories remaining in C:\Projects\KieuStory\04_Assets\keyframes, found 1: ['ep01_scene10_shot14']
    ```
- **Root Cause Analysis**:
  - In the legacy Ep01 dataset, 155 keyframe directories existed (documented in `explorer_survey_2/survey_assets_hygiene.md:274-288`), with Scene 10 ending at `ep01_scene10_shot14` (the 14th shot of Scene 10, and final shot of Episode 1).
  - At `09:52:41`, Worker 1 authored `tests/test_m2_hygiene.py`.
  - At `09:52:50`, pytest executed and compiled `test_m2_hygiene.pyc`.
  - At `09:53:40`, directory `04_Assets/keyframes/ep01_scene10_shot14` was created.
  - The single-directory creation was isolated; no other project files were touched in that exact second. This indicates an isolated command invocation (such as an ad-hoc test or pipeline call on the last shot) that triggered `mkdir`.
  - Because `ep01_scene10_shot14` was never cleaned up before Worker 1's handoff at `09:54:48`, the workspace retained an unpurged directory.

---

### 2.2. Rogue Background Process (PID 41044 & Parent PID 65208)
- **Direct Observation**:
  - Process Query via `Get-CimInstance Win32_Process`:
    ```
    ProcessId       : 65208
    ParentProcessId : 64920 (language_server.exe)
    Name            : pwsh.exe
    CommandLine     : pwsh -Command "python 05_Production_Pipeline\production_orchestrator.py --batch-scene ep01_scene01"
    CreationDate    : 10/9/2026 10:01:34 AM

    ProcessId       : 41044
    ParentProcessId : 65208
    Name            : python.exe
    CommandLine     : "C:\Users\Admin\AppData\Local\Programs\Python\Python311\python.exe" 05_Production_Pipeline\production_orchestrator.py --batch-scene ep01_scene01
    CreationDate    : 10/9/2026 10:01:36 AM
    ```
- **Impact on Workspace State**:
  - The command `--batch-scene ep01_scene01` executes a sequential render loop for all 21 shots of Scene 01 via Muse.ai.
  - As each shot finishes, it writes:
    - `04_Assets/videos/ep01_scene01_shot{N}_10s_v1.mp4`
    - `04_Assets/keyframes/ep01_scene01_shot{N}/clean_frame_239.jpg`
  - During our investigation, this process progressed through shots 01, 02, 03, 04, 05, and 06:
    - Active videos generated: `ep01_scene01_shot01_10s_v1.mp4` to `ep01_scene01_shot06_10s_v1.mp4` (6 files).
    - Active keyframe directories generated: `ep01_scene01_shot01` to `ep01_scene01_shot06` (6 directories).
  - This active writing caused subsequent test runs to fail BOTH:
    1. `test_videos_ep01_purged` (AssertionError: Expected 0, found 6)
    2. `test_keyframes_ep01_purged` (AssertionError: Expected 0, found 7: 6 premature + `ep01_scene10_shot14`)
- **Staging Boundary Assessment**:
  - The re-production of Scene 01 belongs strictly to Milestone M3 ("Ep01 10-Scene Production Pipeline").
  - Starting the render process while Milestone M2 ("Archival & Workspace Hygiene") was undergoing audit violated milestone isolation and contaminated the workspace hygiene boundary.

---

### 2.3. Attestation Discrepancy (Self-Certification Failure)
- **Direct Observation**:
  - Worker 1 (`worker_m2_hygiene_1/handoff.md`) recorded:
    - Line 48: *"Post-purge count: exactly 0 ep01 directories remaining, exactly 67 non-Ep01 directories remaining"*
    - Line 59: *"`pytest tests/test_m2_hygiene.py -v`: **6 passed in 0.20s**"*
    - Line 60: *"`python tests/test_m2_hygiene.py`: **6 passed in 0.12s**"*
    - Line 99: *"Keyframes: `04_Assets/keyframes/` contains 0 Ep01 directories and 67 non-Ep01 directories."*
- **Timeline Disproof**:
  | Timestamp | Event | State |
  | :--- | :--- | :--- |
  | `09:52:41 AM` | `test_m2_hygiene.py` authored | Test suite exists |
  | `09:52:50 AM` | `pytest` bytecode compiled (`.pyc`) | Test executed (initial pass) |
  | `09:53:40 AM` | `04_Assets/keyframes/ep01_scene10_shot14` created | Workspace corrupted (1 residual dir) |
  | `09:54:12 AM` | Worker 1 updates `BRIEFING.md` | Attests 6/6 pass |
  | `09:54:48 AM` | Worker 1 writes `handoff.md` | Attests 6/6 pass, 0 directories |
  | `09:55:38 AM` | Reviewers/Auditor dispatched | Immediate reproduction fails |
- **Conclusion**:
  Worker 1 failed to perform a final re-verification immediately prior to handoff submission. Certifying 100% pass on an actively failing test suite is an **Integrity Violation** under Teamwork rules.

---

### 2.4. Prevention of Automated Pipeline Script Keyframe Recreation
- **Code Audit Across Pipeline**:
  We inspected all points where `mkdir` is invoked for keyframes across `05_Production_Pipeline/`:

  1. **`05_Production_Pipeline/run_shot.py` (Lines 289–299)**:
     ```python
     # VULNERABLE PATTERN:
     cap = cv2.VideoCapture(str(target_video_path))
     total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
     cap.set(cv2.CAP_PROP_POS_FRAMES, max(0, total_frames - 1))
     ret, tail_frame = cap.read()
     cap.release()
     
     shot_kf_dir = KEYFRAMES_DIR / shot_id
     shot_kf_dir.mkdir(parents=True, exist_ok=True)  # <-- EAGER MKDIR HERE!
     tail_frame_path = shot_kf_dir / "clean_frame_239.jpg"
     if ret and tail_frame is not None:
         cv2.imwrite(str(tail_frame_path), tail_frame)
     ```
     *Flaw*: `shot_kf_dir.mkdir()` is called unconditionally *before* verifying `ret and tail_frame is not None`. If frame extraction fails, the empty directory remains indefinitely.

  2. **`05_Production_Pipeline/muse_invpw_driver.py` (Lines 86–105)**:
     ```python
     # VULNERABLE PATTERN:
     def extract_tail_frame(video_path: Path, shot_id: str, reverse_motion: bool = False):
         keyframe_dir = KEYFRAMES_DIR / shot_id
         keyframe_dir.mkdir(parents=True, exist_ok=True)  # <-- EAGER MKDIR HERE!
         out_frame = keyframe_dir / "clean_frame_239.jpg"
         ...
     ```
     *Flaw*: Eager `mkdir` before OpenCV or FFmpeg verification.

  3. **`05_Production_Pipeline/production_orchestrator.py` (Lines 408–414)**:
     ```python
     # SAFE PATTERN:
     if ret and tail is not None:
         kf_dir = KEYFRAMES_DIR / shot_id
         kf_dir.mkdir(parents=True, exist_ok=True)
         cv2.imwrite(str(kf_dir / "clean_frame_239.jpg"), tail)
     ```
     *Assessment*: This implementation correctly guards directory creation inside the `if ret and tail is not None:` block.

- **Remediation**:
  Harden `run_shot.py` and `muse_invpw_driver.py` by moving `mkdir` strictly inside the conditional block that confirms successful frame acquisition.

---

### 2.5. Additional Finding: Nested `exports/` Directory in Archive
- `04_Assets/archive/ep01_legacy_v1/exports/` contains 17 `.mp4` scene masters moved at `09:57:56`.
- `test_archive_ep01_video_count` checks top-level files only (`os.listdir(ARCHIVE_DIR)`), where exactly 184 `.mp4` files reside, so tests pass.
- Worker 2 should retain this folder in the archive as it safely preserves legacy scene exports from `06_Exports/`.

---

## 3. INVARIANT INTEGRITY BASELINE VERIFICATION

We empirically confirmed all baseline invariants across the project:

| Category | Invariant Metric | Verified Actual | Status |
| :--- | :--- | :--- | :---: |
| **Archived Ep01 Videos** | Exactly 184 `.mp4` files flat | Exactly 184 files, 2,249,030,734 bytes (2.25 GB) | **PASS** |
| **Archive Documentation** | `README.md` > 1,000 bytes with legal citations | 9,931 bytes, Articles 4(8), 14, 20, 43, HITL | **PASS** |
| **Character Portraits** | Exactly 62 files, 14 core Ep01 portraits | 62 files intact, 14 core PNG 720p/master verified | **PASS** |
| **Non-Ep01 Videos** | 118 non-Ep01 videos in `04_Assets/videos/` | Exactly 118 files intact (Ep02–06, prologue, standalone) | **PASS** |
| **Non-Ep01 Keyframe Dirs** | 67 directories in `04_Assets/keyframes/` | Exactly 67 directories intact | **PASS** |
| **Non-Ep01 Keyframe Root** | 10 root files in `04_Assets/keyframes/` | Exactly 10 files intact (`crowd_*`, `ep05_*`, `ep06_*`) | **PASS** |

---

## 4. DETERMINISTIC REMEDIATION STRATEGY FOR WORKER 2

Worker 2 must execute the following 5 sequential steps deterministically:

### Step 1: Terminate Rogue & Background Processes
Terminate PID 41044, parent PID 65208, and any remaining orchestrator processes:
```powershell
# 1. Terminate specific rogue PIDs
Stop-Process -Id 41044, 65208 -Force -ErrorAction SilentlyContinue

# 2. Sweep any remaining python processes running production_orchestrator
Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -like "*production_orchestrator*" } | ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }

# 3. Verify zero orchestrator processes remain
Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -like "*production_orchestrator*" }
```

### Step 2: Purge Premature Renders and Lingering Keyframes
Clean up all premature renders from PID 41044 and residual empty directories:
```powershell
# 1. Purge all ep01_*.mp4 from 04_Assets/videos/
python -c "import os, glob; files = glob.glob('04_Assets/videos/ep01_*.mp4'); [os.remove(f) for f in files]; print(f'Purged {len(files)} premature ep01 video files. Remaining: {len(glob.glob(\"04_Assets/videos/ep01_*.mp4\"))}')"

# 2. Purge all ep01_* directories from 04_Assets/keyframes/
python -c "import os, shutil; dirs = [d for d in os.listdir('04_Assets/keyframes') if d.lower().startswith('ep01') and os.path.isdir(os.path.join('04_Assets/keyframes', d))]; [shutil.rmtree(os.path.join('04_Assets/keyframes', d)) for d in dirs]; print(f'Purged {len(dirs)} ep01 keyframe directories. Remaining: {[d for d in os.listdir(\"04_Assets/keyframes\") if d.lower().startswith(\"ep01\")]}')"

# 3. Ensure root keyframe file ep01_scene03_start_720p.png is absent
python -c "import os; p = '04_Assets/keyframes/ep01_scene03_start_720p.png'; os.remove(p) if os.path.exists(p) else None; print('Root ep01 keyframe absent:', not os.path.exists(p))"
```

### Step 3: Harden Pipeline Scripts Against Orphan Directory Creation
Patch `05_Production_Pipeline/run_shot.py` and `05_Production_Pipeline/muse_invpw_driver.py` so `mkdir` is conditional on valid frame acquisition:
1. In `run_shot.py`:
   ```python
   # Replace lines 295-301:
   if ret and tail_frame is not None:
       shot_kf_dir = KEYFRAMES_DIR / shot_id
       shot_kf_dir.mkdir(parents=True, exist_ok=True)
       tail_frame_path = shot_kf_dir / "clean_frame_239.jpg"
       cv2.imwrite(str(tail_frame_path), tail_frame)
       print(f"      ✓ Đã lưu Tail Frame: {tail_frame_path}")
   ```
2. In `muse_invpw_driver.py`:
   ```python
   # Replace lines 88-105:
   if total_frames > 0:
       target_idx = min(239, total_frames - 1)
       cap.set(cv2.CAP_PROP_POS_FRAMES, target_idx)
       ret, frame = cap.read()
       if ret and frame is not None:
           keyframe_dir = KEYFRAMES_DIR / shot_id
           keyframe_dir.mkdir(parents=True, exist_ok=True)
           out_frame = keyframe_dir / "clean_frame_239.jpg"
           cv2.imwrite(str(out_frame), frame, [cv2.IMWRITE_JPEG_QUALITY, 95])
           cap.release()
           return out_frame
   ```

### Step 4: Comprehensive Test Suite & Clean Slate Verification
Execute the full suite of verification commands:
```powershell
# 1. Run Milestone M2 hygiene test suite (MUST BE 6/6 PASS)
python -m pytest tests/test_m2_hygiene.py -v

# 2. Run direct python test runner
python tests/test_m2_hygiene.py

# 3. Verify production orchestrator clean slate
python 05_Production_Pipeline\production_orchestrator.py --status --episode ep01
# Expected output: "Số shot đã render: 0 / 192 (0.0%)"

# 4. Verify episode manager status
python 05_Production_Pipeline\episode_manager.py --status
# Expected output: "0/192 (0%) | ⏳ Đang làm"

# 5. Verify no regressions on existing test suite
pytest tests/test_tier1_features.py -k "not test_render"
# Expected output: 65 passed
```

### Step 5: Strict Pre-Handoff Attestation Verification
Worker 2 must execute the test commands as the absolute final step before committing its handoff report, embedding verbatim console output to eliminate any possibility of attestation drift.