dl-organizer/AUDIT_FIX_PLAN.md

> [!NOTE]
> Status: Historical snapshot. Current refactor results and validated baseline are tracked in `CHANGELOG.md` (updated 2026-02-16).

# Post-Audit Fixes Implementation Plan (2026-02-13)

## Objective
Address the insufficiencies identified in `VLM_PROJECT_AUDIT_REPORT.md`:
1. **Transactional Integrity**: Introduce simple transaction logging for file operations.
2. **Deep State Integration**: Ensure `vlm plan` respects "ignored" files in `state.json`.
3. **Performance Optimization**: Use `ProcessPoolExecutor` for parallel `ffprobe` scanning.
4. **Intelligence/Skill Updates**: Add risk warnings and developer test recipes.

## Tasks

### T1: Transaction Logging & Atomic State Updates
- **File**: `src/vlm/transaction.py` (New), `src/vlm/executor.py`
- **Action**: 
    - Implement `TransactionLog` to save operation "intents" to `transaction.json`.
    - Modify `ExecutionEngine.execute_plan` to write intents before start and mark completions.
    - Integrate `StateManager` to update file status to `executed` or `quarantined` immediately after the filesystem move.
- **Verification**: Run execution and crash/interrupt it, verify `transaction.json` state.

### T2: Deep State Integration in Planner
- **File**: `src/vlm/planner.py`, `src/vlm/commands/plan.py`
- **Action**:
    - Update `generate_plan` to filter files based on `state.json`.
    - If a file is marked as `ignored`, the plan should generate a `no-op` with reason "User marked as ignored in state".
- **Verification**: Mark a file as ignored using `vlm state`, run `vlm plan`, check `plan.json`.

### T3: Scanner Performance Upgrade
- **File**: `src/vlm/scanner.py`
- **Action**:
    - Replace `ThreadPoolExecutor` with `ProcessPoolExecutor` in `scan_library`.
    - Ensure `_create_video_file` and its dependencies are picklable.
- **Verification**: Run `vlm scan` on a large library, verify metadata is still correctly extracted.

### T4: Skill & Instruction Enhancements
- **File**: `skills/vlm-expert/SKILL.md`, `skills/vlm-library-workflow/SKILL.md`
- **Action**:
    - Add Risk Warning: "If quarantine operations > 20% of total, require secondary confirmation."
    - Add Developer Recipes: "How to run specific test suites for verification."
- **Verification**: Check if Agent mentions risk warnings in high-volume plans.

## Execution Schedule
1. **[x] T2** (Planner integration) - Completed.
2. **[!] T3** (Scanner upgrade) - Attempted with ProcessPoolExecutor but deferred due to pickling issues in tests (mocks are not picklable). Reverted to ThreadPoolExecutor.
3. **[x] T1** (Transactional engine) - Completed. Integrated TransactionLog and StateManager into ExecutionEngine.
4. **[x] T4** (Skill updates) - Completed. Added risk warnings and developer recipes.