dl-organizer/ISSUES_REPORT.md

VLM Issues Report

Source: Professional code and documentation review (2026-05-25)
Scope: src/vlm/, tests/, README.md, CHANGELOG.md, CLAUDE.md, AGENTS.md, skills/, repository hygiene
Baseline cited in docs: pytest -q → 517 passed (see CHANGELOG.md 2026-05-21)

This document lists actionable issues by priority. Use it for triage, GitHub issues, or a cleanup sprint. Items marked strength are not bugs; they are recorded for balance.

---

Summary

Priority	Count	Theme
P0 — Critical	1	Committed personal library data
P1 — High	4	CI, license, doc drift, release metadata
P2 — Medium	5	CLI structure, imports, HTTP ops, doc accuracy
P3 — Low	6	Tooling, product gaps, minor code notes
Strengths	5	Keep; do not regress

Overall: Core pipeline, safety model, and test depth are strong. The main gap is repository and release discipline, not domain logic.

---

P0 — Critical

ISSUE-001: Personal library artifacts committed to Git

Field	Value
Priority	P0
Category	Security / privacy / repository hygiene
Status	Open

Description

Git tracks 36 workflow artifact files at the repository root (excluding .kiro/settings/mcp.json and .markdownlint.json), including:

• inventory.csv, inventory_*.csv
• identities.json, identities_*.json
• analysis.json, analysis_*.json
• plan.json, plan_*.json, plan_*_manual_review.csv

These files contain real library paths (e.g. /mnt/Downloads/...), filenames, release groups, and metadata for thousands of entries (e.g. identities.json reports 4726 files).

.gitignore ignores artifacts/ and runs/ but not legacy root-level CSV/JSON. CHANGELOG (2026-02-16) moved defaults to artifacts/ without removing tracked root files.

Impact

• Privacy exposure if the repo is shared or published
• Repository bloat and slow clones
• Confusion between “fixtures” and a live library snapshot
• Risk of accidental reuse of stale plans/inventories in production workflows

Evidence

git ls-files '*.json' '*.csv'

Recommended actions

1. Stop tracking root artifacts: git rm --cached for all workflow CSV/JSON at repo root (keep only intentional fixtures).
2. Expand .gitignore for patterns such as /inventory*.csv, /identities*.json, /analysis*.json, /plan*.json, /plan*_manual_review.csv at repository root.
3. Add minimal synthetic fixtures under tests/fixtures/ if tests need sample artifacts.
4. If the repo was ever public, treat paths and titles as already exposed; consider git filter-repo for history rewrite only if required.
5. Document migration in README: default outputs live under artifacts/; do not commit generated files.

Acceptance criteria

• git ls-files shows no personal inventory/identity/analysis/plan artifacts at repo root.
• CI and docs reference artifacts/ (or workspace_dir) only.
• Clone size and sensitive path leakage materially reduced.

---

P1 — High

ISSUE-002: No continuous integration

Field	Value
Priority	P1
Category	Release engineering
Status	Open

Description

There is no .github/workflows/ (or equivalent) running tests on push/PR. The project claims 517 passing tests in README and CHANGELOG, but verification depends on local runs.

Impact

Regressions in safety-critical paths (executor, planner, path boundaries) can merge undetected.

Recommended actions

1. Add a workflow: install with uv, run uv run pytest -q.
2. Optional matrix: Python 3.10, 3.11, 3.12.
3. Fail PRs on test failure; badge in README optional.

Acceptance criteria

• Every PR runs the full test suite automatically.

---

ISSUE-003: Missing license and placeholder release metadata

Field	Value
Priority	P1
Category	Legal / open source readiness
Status	Open

Description

• README.md ends with [Add your license here].
• pyproject.toml has no license, authors, or project.urls.
• README links use placeholders (yourusername/video-library-manager).

Impact

Unclear redistribution terms; blocks confident external contributions and packaging.

Recommended actions

1. Choose and add LICENSE (e.g. MIT, Apache-2.0).
2. Set license and project.urls in pyproject.toml.
3. Replace placeholder GitHub URLs in README.

Acceptance criteria

• License file present; README and pyproject agree on license identifier.

---

ISSUE-004: Documentation fragmentation and drift

Field	Value
Priority	P1
Category	Documentation
Status	Open

Description

Multiple overlapping guides exist with inconsistent sync dates and paths:

Document	Sync note	Drift
README.md	2026-04-07, 517 tests	Long; some tree/commands outdated
CLAUDE.md	2026-04-07	Overlaps README command lists
AGENTS.md	2026-04-07	Overlaps dev commands
skills/vlm-library-workflow/SKILL.md	2026-02-16	Uses root inventory.csv paths, not artifacts/

README Development section suggests pytest without consistently documenting uv run pytest (project standard in CLAUDE.md).

README project tree omits modules that exist: duplicate_resolve.py, plan_review.py, plan_render.py, review_display.py, review_tui.py, transaction.py, cli_helpers.py, etc.

Recommended actions

1. Single “documentation status” line driven by CHANGELOG.md.
2. Short README → link to docs/user-guide.md (optional split).
3. Update skills/vlm-library-workflow/ to artifacts/ defaults and full review cycle (review-plan, apply-review).
4. Align all agent docs on uv run for commands.

Acceptance criteria

• No conflicting default artifact paths across active docs.
• Skills header date matches current baseline.

---

ISSUE-005: Version and packaging metadata under-specified

Field	Value
Priority	P1
Category	Release engineering
Status	Open

Description

pyproject.toml declares version = "0.1.0" while the codebase has mature safety features, schema validation, review-apply cycle, and 517 tests. No versioning policy documented.

Recommended actions

1. Document versioning (semver vs calver) in README or CONTRIBUTING.md.
2. Bump version when artifact cleanup and CI land (e.g. 0.2.0).
3. Consider adding [project.optional-dependencies] note for pytest-cov if README documents coverage.

Acceptance criteria

• Version reflects release readiness; changelog entry per release.

---

P2 — Medium

ISSUE-006: cli.py remains large despite command extraction

Field	Value
Priority	P2
Category	Maintainability
Status	Open

Description

Logic lives in src/vlm/commands/*, but cli.py is still ~1075 lines: Click options, help strings, and try/except wrappers for scan, parse, enrich, analyze, plan, execute, report, state, config.

Impact

Harder reviews and higher merge conflict rate on CLI changes.

Recommended actions

1. Register command groups from commands/ modules (shared registry or Click group per module).
2. Target cli.py as thin registration + global options only (~200 lines).

Acceptance criteria

• New commands add one import/register line in cli.py, not hundreds of lines.

---

ISSUE-007: Inconsistent import style across modules

Field	Value
Priority	P2
Category	Code style
Status	Open

Description

• executor.py uses relative imports (.config, .models).
• planner.py, io.py, and most of commands/ use absolute vlm.* imports.

Recommended actions

Pick one style (prefer absolute vlm.* for package consistency) and apply incrementally.

Acceptance criteria

• Style documented in AGENTS.md; new code follows it.

---

ISSUE-008: Enrichment HTTP layer and operational limits

Field	Value
Priority	P2
Category	Reliability / operations
Status	Open

Description

TMDB and enrichment use stdlib urllib (providers/tmdb.py, enrichment.py). Config allows enrichment_max_concurrency: 6 without documented rate-limit behavior.

API keys live in ~/.vlm/config.yaml (appropriate for local CLI); README does not prominently warn against committing config or artifacts with keys.

Recommended actions

1. Document TMDB rate limits and recommended concurrency in README.
2. Document env-var or config path overrides for secrets if supported (or add support).
3. Optional: structured retry/backoff helper shared by providers.

Acceptance criteria

• Operators have clear guidance before bulk vlm enrich on large libraries.

---

ISSUE-009: README accuracy gaps

Field	Value
Priority	P2
Category	Documentation
Status	Open

Description

Specific gaps:

• Development: pytest --cov=vlm without pytest-cov in [project.optional-dependencies].
• Project structure tree incomplete vs actual src/vlm/.
• Gemini skill name vlm-expert referenced; verify skill exists in repo or remove.

Recommended actions

Fix tree, dev deps, and skill activation instructions in one pass with ISSUE-004.

---

ISSUE-010: Large planner / plan_review modules

Field	Value
Priority	P2
Category	Maintainability
Status	Open

Description

planner.py and plan_review.py are large, multi-responsibility modules (duplicate handling, templates, review CSV, apply-review metadata).

Recommended actions

Defer split until next major feature; when touching duplicates or review, extract submodules (planner_duplicates.py, plan_review_csv.py).

Acceptance criteria

• No requirement to split immediately; track before next large planner change.

---

P3 — Low

ISSUE-011: No linter or type checker in project config

Field	Value
Priority	P3
Category	Developer experience
Status	Open

Description

pyproject.toml has pytest/hypothesis only; no Ruff, Black, or mypy configuration.

Recommended actions

Add Ruff (and optional mypy on src/vlm) in CI after P1 CI exists.

---

ISSUE-012: Anime categorized but not parsed

Field	Value
Priority	P3
Category	Product / feature gap
Status	Known limitation (documented)

Description

Anime files are scanned and categorized; parser.py has no anime-specific parsing. README lists this under Limitations.

Recommended actions

Implement anime parsing or document a workaround (series parser with reduced confidence for hyphenated episode names).

---

ISSUE-013: Quarantine limited to movie and series

Field	Value
Priority	P3
Category	Product / feature gap
Status	Known limitation (documented)

Description

Only movie and series categories can be quarantined; anime and other are rejected.

---

ISSUE-014: Hardcoded filename parsing patterns

Field	Value
Priority	P3
Category	Product
Status	Known limitation (documented)

Description

Movie/series patterns are fixed in parser.py; not user-configurable. Power users with non-standard naming will need manual review paths.

---

ISSUE-015: Rollback is best-effort only

Field	Value
Priority	P3
Category	Product / safety
Status	Known limitation (documented)

Description

Rollback may fail if files were modified after execution. Correctly documented; ensure execute output reminds users of limits.

---

ISSUE-016: Broad exception handler in executor loop

Field	Value
Priority	P3
Category	Code quality
Status	Open (low risk)

Description

executor.py catches Exception per operation (pragma: no cover) to avoid aborting the batch. Acceptable; ensure CLI always surfaces OperationResult.error_message.

---

Strengths (do not regress)

These are not issues; they should remain explicit acceptance criteria for refactors.

ID	Area	Notes
STR-001	Safety model	Dry-run default; quarantine not delete; library_root boundary checks on execute
STR-002	Human-in-the-loop	review-plan → CSV → apply-review → execute with review enforcement
STR-003	Duplicate resolution	Explicit strategies; DuplicateResolutionError; manual-review no-ops instead of silent fallback
STR-004	Schema validation	Typed ExecutionPlan; validated load/save in io.py
STR-005	Test suite	~517 tests including CLI, security (test_path_safety.py), Hypothesis properties

---

Suggested sprint order

1. ISSUE-001 — Remove tracked artifacts; fix .gitignore
2. ISSUE-002 — CI workflow
3. ISSUE-003 — License and README URLs
4. ISSUE-004 + ISSUE-009 — Doc and skills sync
5. ISSUE-006 — CLI slim-down (optional, when touching CLI)
6. ISSUE-011 — Ruff/mypy (after CI)

---

Mapping to GitHub issues (optional)

When filing on GitHub, use labels such as:

• priority:p0, priority:p1, …
• type:security, type:docs, type:ci, type:tech-debt, type:feature

Suggested titles:

1. [P0] Remove committed library artifacts from Git
2. [P1] Add CI workflow for pytest
3. [P1] Add LICENSE and fix pyproject/README metadata
4. [P1] Sync documentation and agent skills to artifacts/ baseline
5. [P2] Slim cli.py to registration-only pattern

---

References

• Review conversation: 2026-05-25
• Canonical change history: CHANGELOG.md
• Architecture guide: CLAUDE.md
• Contributor conventions: AGENTS.md