chore: trim dead code, modularize CLI, and archive stale docs

Extract review-plan, report, quarantine, state, and config handlers into commands/ with shared cli_helpers; remove unused exceptions and duplicate plan summary wrappers. Archive superseded review markdown, sync docs to 517-test baseline, and fix empty series titles when only a quality tag remains. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-21 10:36:03 +08:00
parent 5f0b531269
commit 79797644e1
40 changed files with 1714 additions and 1165 deletions
@@ -0,0 +1,48 @@
+> [!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.