dl-organizer/CHANGELOG.md

# Changelog

## 2026-04-02

### Schema Validation & Deterministic Planning

- Added runtime validation for `identities.json`, `analysis.json`, and `plan.json` on load/save.
- Plan generation now records environment-derived checks in `validation_snapshot` metadata, keeping logical plan output reproducible.
- Added targeted regression tests for plan round-trip validation and invalid-schema rejection.
- Verified the affected workflows with `uv run pytest tests/test_io.py tests/test_planner.py`.


### Logic Optimization & Human-in-the-Loop

- **Human-in-the-Loop Workflow Completion**:
  - Added `vlm apply-review` command to sync modifications from `plan_manual_review.csv` back to `plan.json`.
  - Implemented `apply_review_to_plan` in `src/vlm/planner.py` to allow manual rejection/modification of high-risk operations via CSV.

- **Scanner Robustness & Environment Awareness**:
  - Added proactive `ffprobe` availability check at the start of `vlm scan`.
  - Implemented graceful degradation: if `ffprobe` is missing, the scanner automatically falls back to file-only metadata mode with a clear warning, instead of failing per-file.

- **Parser Enhancements**:
  - Improved `src/vlm/parser.py` to better handle release group tags (`[Group]`, `(Group)`, `Group_Subs`).
  - Added support for hyphenated episode numbering (e.g., `Name - 01`) common in Anime, defaulting to Season 1 with reduced confidence.
  - Refined release group removal to be more robust against various bracket styles.

- **CLI & UX**:
  - `vlm review-plan` now prints a plan overview plus a structured high-risk operation preview in terminal output.
  - Added `--preview-limit` and `--show-all` to control review-plan preview verbosity.
  - Added shared plan rendering helpers so `review-plan` and `execute` reuse the same summary fallback behavior.
  - Added `vlm apply-review` to the main CLI group.

## 2026-02-16

### Artifact Path Governance

- Changed default workflow artifact outputs from repository root to `artifacts/`:
  - `artifacts/inventory.csv`
  - `artifacts/identities.json`
  - `artifacts/analysis.json`
  - `artifacts/plan.json`
  - `artifacts/plan_manual_review.csv`
- Added `workspace_dir` to configuration (`~/.vlm/config.yaml`) to customize default artifact directory.
- Stage-A compatibility: when a command uses default input path and only legacy root artifact exists, CLI now prints a migration warning and falls back to the legacy file.
- Added ignore rules for generated artifact directories in `.gitignore` (`artifacts/`, `runs/`).
- Removed temporary process document `ARTIFACTS_REFACTOR_PLAN_2026-02-16.md`; `CHANGELOG.md` remains the canonical change record.

### Refactor Results

- Modularized CLI command implementations:
  - Added `src/vlm/commands/parse.py`
  - Added `src/vlm/commands/enrich.py`
  - Added `src/vlm/commands/execute.py`
  - Refactored `src/vlm/cli.py` to delegate `parse`, `enrich`, `execute`, and `rollback` to command modules

- Unified I/O layer for JSON handling:
  - Added `load_json_file`, `save_json_file`, `save_analysis_json` in `src/vlm/io.py`
  - Updated analyze/enrich paths to use unified I/O entry points

- Parser/config consistency improvements:
  - Added shared `DEFAULT_VIDEO_EXTENSIONS` in `src/vlm/config.py`
  - Updated `src/vlm/parser.py` to use the shared config constant instead of local hardcoded defaults

- Execution reliability hardening:
  - Updated `src/vlm/executor.py` transaction logging to fail gracefully when `~/.vlm` is not writable (warn + continue)

- Test stability improvements:
  - Standardized test timestamps to timezone-aware UTC (`datetime.now(timezone.utc)`)
  - Added missing `timezone` imports where required

### Verification

- Full test suite passed after refactor:
  - `477 passed`

### Documentation Sync

- Updated repository documentation set to match the refactor baseline:
  - Core docs: `README.md`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`
  - Skill docs: `skills/vlm-library-workflow/SKILL.md` and all references under `skills/vlm-library-workflow/references/`
  - Legacy review/plan docs now explicitly marked as historical snapshots and redirected to `CHANGELOG.md` as the current source of truth