dl-organizer/plans/2026-04-07-review-report-refactor-plan-v1.md

Refactor Plan: Safety, Determinism, and Baseline Alignment

Date: 2026-04-07
Basis: Verified repository state plus REVIEW_REPORT.md.
Status: Completed.

Objective

Refactor the codebase to resolve the safety and determinism issues identified during review, restore a truthful green baseline, and reconcile the review artifacts with the post-refactor state.

Execution Outcome

• Full-suite baseline restored: pytest -q → 507 passed.
• The review-plan TUI is now a true optional runtime boundary via guarded Textual imports in src/vlm/review_tui.py:16-30 and lazy CLI import/use in src/vlm/cli.py:567-602.
• Move and rename execution now validate both source and destination paths against library_root in src/vlm/executor.py:204-249.
• Duplicate handling is now explicit and deterministic through strict resolver errors in src/vlm/duplicate_resolve.py:16-58 plus canonicalized planner matching and manual-review fallback in src/vlm/planner.py:42-57 and src/vlm/planner.py:151-203.
• Scanner behavior for non-zero find exits is now documented in code and deterministic in src/vlm/scanner.py:158-214.
• Plan loading now crosses a validated typed boundary in src/vlm/io.py:247-326.

Implementation Plan

• Task 1. [Status: Done] Re-established a reliable baseline by making the Textual review UI a true optional boundary. Evidence: src/vlm/cli.py:567-602, src/vlm/review_tui.py:16-30, tests/test_cli_review_plan.py:237-343.
• Task 2. [Status: Done] Added source-root validation for move and rename operations so execution checks both source and destination against library_root. Evidence: src/vlm/executor.py:204-249, tests/test_path_safety.py:76-137.
• Task 3. [Status: Done] Unified execution failure contracts so unsupported quarantine categories now return failed OperationResults, and batch execution contains per-operation exceptions. Evidence: src/vlm/quarantine.py:116-140, src/vlm/executor.py:108-130, tests/test_quarantine.py:84-110, tests/test_executor.py:951-1004.
• Task 4. [Status: Done] Removed silent duplicate fallback behavior by raising explicit resolver errors and routing unresolved groups into manual review. Evidence: src/vlm/duplicate_resolve.py:44-58, src/vlm/planner.py:187-203, tests/test_duplicate_resolve.py:223-237, tests/test_planner.py:619-669.
• Task 5. [Status: Done] Introduced canonical path-normalization for duplicate-group matching. Evidence: src/vlm/planner.py:42-57, src/vlm/planner.py:152-169, tests/test_planner.py:672-720.
• Task 6. [Status: Done] Defined and implemented an explicit scanner contract for non-zero find exits with partial or empty stdout. Evidence: src/vlm/scanner.py:158-214, tests/test_scanner.py:140-186.
• Task 7. [Status: Done] Strengthened the plan I/O boundary with validated typed construction and canonical serialization helpers. Evidence: src/vlm/io.py:247-326, tests/test_io.py:112-203.
• Task 8. [Status: Done] Expanded regression coverage around the identified weak points. Evidence: tests/test_cli_review_plan.py:237-343, tests/test_path_safety.py:76-137, tests/test_quarantine.py:84-110, tests/test_executor.py:951-1004, tests/test_duplicate_resolve.py:223-237, tests/test_planner.py:619-720, tests/test_scanner.py:140-186, tests/test_io.py:112-203.
• Task 9. [Status: Done] Updated existing review artifacts to reflect the final baseline and current findings. Evidence: REVIEW_REPORT.md, docs/TECHNICAL_REVIEW.md.

Verification Criteria

• pytest -q passes, including the review-plan TUI tests in tests/test_cli_review_plan.py:271-343.
• Manual or crafted plans cannot move or rename sources outside library_root. Evidence: src/vlm/executor.py:204-249, tests/test_path_safety.py:106-137.
• Unsupported quarantine categories are recorded as failed results and do not abort later operations in the same execution batch. Evidence: src/vlm/quarantine.py:116-140, src/vlm/executor.py:108-130, tests/test_executor.py:951-1004.
• Duplicate resolution no longer silently selects index 0 for quality-data mismatch or unexpected low-level strategy input. Evidence: src/vlm/duplicate_resolve.py:44-58, tests/test_duplicate_resolve.py:223-237, tests/test_planner.py:619-669.
• Duplicate-group matching is stable across supported path-format variations and covered by planner tests. Evidence: src/vlm/planner.py:42-57, tests/test_planner.py:672-720.
• Scanner behavior for non-zero find exit is explicit, deterministic, and test-covered. Evidence: src/vlm/scanner.py:158-214, tests/test_scanner.py:140-186.
• Plan loading crosses one validated, typed boundary rather than propagating plain dicts after schema validation. Evidence: src/vlm/io.py:247-326, tests/test_io.py:112-203.
• Existing review documents reflect the actual test baseline and remaining findings.

Post-plan Note

The refactor plan is complete. One low-priority packaging observation remains outside the implementation scope: textual is still listed in both dev and tui optional extras in pyproject.toml:12-20. The runtime optional-dependency bug itself is resolved via src/vlm/cli.py:567-602 and src/vlm/review_tui.py:16-30.