dl-organizer/docs/archive/2026-pre-baseline/FIX_PLAN.md

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