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

```bash
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`