# 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.