dl-organizer/AUDIT_FIX_PLAN.md

Note

Status: Historical snapshot. Current refactor results and validated baseline are tracked in CHANGELOG.md (updated 2026-04-07).

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.