> [!NOTE]
> Status: Historical snapshot. Current refactor results and validated baseline are tracked in `CHANGELOG.md` (updated 2026-04-07).

# Fix Plan (Verified Issues Only)

## Objective
- Repair only verified defects from `REVIEW_REPORT.md`.
- Keep behavior stable outside defect scope.
- Ensure every fix is testable and reproducible.

## Definition of Done
- `uv run --with pytest --with hypothesis pytest -q` passes.
- No test imports use `src.vlm...`.
- Timestamp handling outputs correct UTC instants.
- Logging remains usable when file log path is unwritable.
- Default home-based paths are resolved at runtime, not import time.

## Phase 0 - Baseline and guardrails
- Run baseline suite and keep output:
  - `uv run --with pytest --with hypothesis pytest -q`
- Record current known failures for before/after comparison.
- Guardrails:
  - No unrelated refactor.
  - No behavior change outside listed findings.

## Phase 1 - Fix broken test import paths (P1)
- Files:
  - `tests/test_executor.py`
  - `tests/test_quarantine.py`
- Changes:
  - Replace `from src.vlm...` with `from vlm...`.
- Verification:
  - `uv run --with pytest --with hypothesis pytest -q tests/test_executor.py tests/test_quarantine.py`
  - `uv run --with pytest --with hypothesis pytest -q`
- Acceptance:
  - No `ModuleNotFoundError: No module named 'src'`.

## Phase 2 - Fix timezone relabeling bug (P2)
- Files:
  - `src/vlm/scanner.py`
  - `src/vlm/reports.py`
- Changes:
  - Use aware UTC timestamp creation for file mtimes.
  - Remove naive `replace(tzinfo=timezone.utc)` relabeling in export paths.
  - Enforce explicit conversion to UTC instant.
- Tests:
  - Add/extend tests for naive timestamps under non-UTC local timezone assumptions.
  - Assert true instant conversion (not label swap).
- Verification:
  - `uv run --with pytest --with hypothesis pytest -q tests/test_scanner.py tests/test_reports.py`
  - `uv run --with pytest --with hypothesis pytest -q`
- Acceptance:
  - Timestamp tests pass and no relabel bug remains.

## Phase 3 - Remove dead `error_count` logic (P3)
- File:
  - `src/vlm/scanner.py`
- Preferred change:
  - Remove unused `error_count` and dead summary branch.
- Alternative (if product requires count):
  - Increment and propagate count from scan exception paths.
- Verification:
  - `uv run --with pytest --with hypothesis pytest -q tests/test_scanner.py`
- Acceptance:
  - No dead state/branch for error counting.

## Phase 4 - Harden logging setup fallback (P3 risk)
- File:
  - `src/vlm/logging_config.py`
- Changes:
  - Wrap log-dir creation and file handler setup with `try/except (OSError, PermissionError)`.
  - Keep console logging active when file logging cannot initialize.
  - Emit one clear warning about fallback.
- Tests:
  - Add/extend tests to simulate mkdir/file-handler failure.
  - Verify process continues (warning-only behavior).
- Verification:
  - `uv run --with pytest --with hypothesis pytest -q tests/test_logging.py tests/test_cli.py`
  - `uv run --with pytest --with hypothesis pytest -q`
- Acceptance:
  - No command abort when file log path is unwritable.

## Phase 5 - Resolve import-time home defaults (P3 new)
- Files:
  - `src/vlm/logging_config.py`
  - `src/vlm/cli.py`
- Changes:
  - Replace import-time `Path.home()` constants with runtime helper functions.
  - Resolve defaults at function/option execution time.
- Tests:
  - Add/extend monkeypatch tests to prove runtime resolution.
- Verification:
  - `uv run --with pytest --with hypothesis pytest -q tests/test_cli*.py tests/test_logging.py`
  - `uv run --with pytest --with hypothesis pytest -q`
- Acceptance:
  - Defaults follow runtime environment changes in tests and execution.

## Documentation Updates (with code changes)
- `README.md`
  - Add troubleshooting note for logging fallback to console-only.
  - Clarify UTC timestamp expectation in outputs/reports.
- `REVIEW_REPORT.md`
  - Update each issue status (`open` -> `fixed`) with evidence.

## Execution Order
1. Phase 1 (restore full test collection first).
2. Phase 2 (timezone correctness).
3. Phase 3 (dead logic cleanup).
4. Phase 4 (logging resilience).
5. Phase 5 (runtime defaults).
6. Documentation + final full-suite validation.

## Final Validation Checklist
- Run: `uv run --with pytest --with hypothesis pytest -q`
- Spot-check CLI:
  - `vlm --help`
- Confirm no regression in updated modules:
  - `src/vlm/scanner.py`
  - `src/vlm/reports.py`
  - `src/vlm/logging_config.py`
  - `src/vlm/cli.py`