dl-organizer/REVIEW_REPORT.md

Code & Documentation Review Report

Date: 2026-04-07
Reviewer: Forge

Scope

This report was updated by verifying docs/TECHNICAL_REVIEW.md against the current codebase and aligning conclusions to evidence.

Primary verification inputs:

• docs/TECHNICAL_REVIEW.md:1-152
• src/vlm/executor.py:110-112
• src/vlm/executor.py:321-377
• src/vlm/duplicate_resolve.py:36-48
• src/vlm/planner.py:108-111
• src/vlm/quarantine.py:116-129
• src/vlm/scanner.py:178-192
• src/vlm/io.py:225-251
• pyproject.toml:12-20

Validation baseline:

• uv run pytest -q → 496 passed (as recorded in docs/TECHNICAL_REVIEW.md:10).

---

Overall Score

8.0 / 10

Score breakdown

• Module boundaries / pipeline: 8.5/10
• Execution safety (filesystem): 7.0/10
• Planning / duplicate logic: 7.5/10
• Data I/O & validation: 8.0/10
• Error handling consistency: 7.5/10
• Test signal: 8.5/10
• Dependencies: 9.0/10

---

Verified strengths

1. Pipeline and module boundaries are clean and explicit (scan → parse → analyze → plan → execute).

   • src/vlm/commands/scan.py:14-97
   • src/vlm/commands/parse.py:17-166
   • src/vlm/commands/analyze.py:25-124
   • src/vlm/commands/plan.py:14-112
   • src/vlm/commands/execute.py:37-249

2. Defensive safety measures exist in key areas (destination root checks, quarantine manifest two-phase flow, JSON schema checks).

   • src/vlm/executor.py:354-377
   • src/vlm/quarantine.py:221-320
   • src/vlm/io.py:225-251

3. Testing coverage is broad and currently green.

   • docs/TECHNICAL_REVIEW.md:10
   • tests/test_path_safety.py:1-122
   • tests/test_duplicate_resolve.py:1-184

---

Verified findings

F1) Move/Rename source path is not constrained to library_root (High)

• _perform_operation validates destination under root, but does not enforce source under root before rename.
  • src/vlm/executor.py:355-377

Impact: A crafted/manual plan can attempt renames from paths outside managed library boundaries.

---

F2) by_quality silently falls back to first item on quality-data mismatch (Medium)

• choose_keep_index returns index 0 if quality_comparison is missing/misaligned.
  • src/vlm/duplicate_resolve.py:40-43

Impact: Behavior degrades to input-order selection without explicit operator visibility.

---

F3) Duplicate resolution join relies on exact string path matches (Medium)

• Planner builds path_to_index from str(vf.path) and joins using exact string equality.
  • src/vlm/planner.py:108-111

Impact: Path normalization differences (symlink/case/serialization form) can silently exclude items from duplicate handling.

---

F4) Quarantine category rejection raises exception while execute loop lacks per-op guard (Medium)

• Quarantine rejects unsupported categories with raise ValueError.
  • src/vlm/quarantine.py:116-129
• Execute loop iterates operations without local try/except around each operation call.
  • src/vlm/executor.py:110-112

Impact: One invalid quarantine operation can abort the run instead of being recorded as a single failed result.

---

F5) find non-zero exit still allows stdout parsing (Low)

• Scanner logs non-zero return issues but still parses emitted stdout.
  • src/vlm/scanner.py:178-192

Impact: Partial scan results may be accepted without strict failure semantics.

---

F6) Optional dependency overlap (textual in both dev and tui) (Low)

• textual appears in both extras.
  • pyproject.toml:13-20

Impact: Minor install-surface ambiguity.

---

F7) Plan JSON validation returns dict-typed structure at boundary (Informational)

• validate_plan_json validates shape but returns plain dict.
  • src/vlm/io.py:225-251

Impact: Validator/model drift risk over time if object construction paths diverge.

---

F8) Unknown duplicate strategy defaults to first item (Informational)

• Unrecognized strategy falls through to return 0.
  • src/vlm/duplicate_resolve.py:48

Impact: Configuration typo can silently behave as first-seen policy.

---

Advice (priority order)

1. Add source-root validation for move/rename execution path and test for crafted plan source outside root.

   • src/vlm/executor.py:335-377

2. Make by_quality mismatch explicit (error/metadata flag/manual fallback), rather than silent index-0 default.

   • src/vlm/duplicate_resolve.py:40-43

3. Unify quarantine error contract: return failed OperationResult for unsupported categories (avoid run-aborting exception path).

   • src/vlm/quarantine.py:116-129
   • src/vlm/executor.py:110-112

4. Normalize duplicate path keys consistently across analysis emission and planning consumption.

   • src/vlm/planner.py:108-111

5. Harden duplicate strategy validation in config to reject unknown values at load/validate time.

   • src/vlm/duplicate_resolve.py:36-48
   • src/vlm/config.py:224-340

6. Clarify or gate partial scan behavior on find failures (strict mode or stronger warning semantics).

   • src/vlm/scanner.py:178-192

---

Closing

The codebase remains strong in structure and testing discipline. The key improvements are concentrated in execution guardrails and duplicate-resolution determinism. Addressing the top three items above should materially improve operational safety and predictability.