refactor: consolidate skill docs, add anti-drift tests, and apply audit fixes
DLO-13: Restructure vlm-library-workflow skill as safety contract layer. - Rewrite SKILL.md (69 lines): safety contract, execution threshold semantics, six-step high-risk loop, decision rules, phase skeleton - Delete redundant references (cli-reference, workflow, command-recipes, dev-guide) - Add triage.md (failure mapping + preflight) and dev-map.md (module→test mapping) - Add tests/test_docs_consistency.py: 78 parametrized tests verifying documented vlm commands exist in CLI registry - Add CSV path mismatch test to test_plan_review.py (4th safety gate path) - Delete vlm-expert.skill (Gemini package, 7 months stale) and README Gemini section DLO-2 audit fixes: rate limiter injection, symmetric quarantine categories, review-plan safety gates, parser improvements, planner validation. CLI modularization: commands/ directory with one module per command group.
This commit is contained in:
windyboy
@@ -1,96 +1,69 @@
|
||||
# Documentation Status
|
||||
- Synced with artifacts/ baseline on 2026-06-01.
|
||||
|
||||
---
|
||||
name: vlm-library-workflow
|
||||
description: Operate and extend the Video Library Manager (`vlm`) with a safety-first, human-in-the-loop workflow across scan, parse, enrich, analyze, plan, review-plan, apply-review, execute, rollback, and developer verification. Use when requests involve organizing a video library, producing or reviewing `artifacts/inventory.csv`, `artifacts/identities.json`, `artifacts/analysis.json`, `artifacts/plan.json`, tuning VLM config templates, resolving duplicates or episode gaps, running dry-run/confirm execution, recovering changes via rollback, explaining VLM CLI usage, or developing/modifying VLM features (parser, providers, planner, executor, commands, tests).
|
||||
description: Operate and extend the Video Library Manager (vlm) CLI. Use for organizing video libraries (scan/parse/enrich/analyze/plan/execute), reviewing plans, resolving duplicates, or developing VLM features.
|
||||
---
|
||||
|
||||
# VLM Library Workflow
|
||||
|
||||
## Overview
|
||||
## Safety Contract
|
||||
|
||||
Run the repository's built-in media organization pipeline with consistent safety checks and explicit output verification. Prefer incremental, reviewable steps and never skip dry-run and plan inspection before destructive operations.
|
||||
1. Before `execute --confirm`, always run `review-plan` and report `High-risk operations` count.
|
||||
2. If high-risk > 0: **stop**, wait for explicit user decision.
|
||||
3. `--confirm` requires `--require-review` to enforce review gate; default does not force.
|
||||
4. Never run `execute --confirm` without user confirmation.
|
||||
|
||||
**Do not commit** generated CSV/JSON under `artifacts/` or at the repository root.
|
||||
## Execution Threshold Semantics
|
||||
|
||||
## Workflow Order
|
||||
- `high_risk_operations`: count of non-no-op operations with risk flags (printed by `review-plan`).
|
||||
- `review_export_rows`: internal count (not printed); may be larger. Do not use `wc -l` on CSV.
|
||||
- If export row count is needed, parse CSV data rows or add the count to CLI output.
|
||||
|
||||
Run commands in this default sequence unless the user asks for a specific stage:
|
||||
## High-Risk Closed Loop
|
||||
|
||||
1. `vlm config init` then set `library_root` in `~/.vlm/config.yaml`
|
||||
2. `vlm scan` → `artifacts/inventory.csv`
|
||||
3. `vlm parse --inventory artifacts/inventory.csv` → `artifacts/identities.json` (v2 schema)
|
||||
4. `vlm enrich` when bilingual titles and reputation signals are needed
|
||||
5. `vlm analyze --inventory artifacts/inventory.csv` → `artifacts/analysis.json`
|
||||
6. `vlm plan --analysis artifacts/analysis.json` → `artifacts/plan.json`
|
||||
7. `vlm review-plan` → `artifacts/plan_manual_review.csv` (use `--tui` only when Textual is installed)
|
||||
8. Edit CSV if needed, then `vlm apply-review` to sync decisions into `plan.json`
|
||||
9. `vlm execute` (dry-run) and inspect summary
|
||||
10. `vlm execute --confirm` only after explicit user confirmation
|
||||
11. `vlm rollback` if the user requests revert
|
||||
When high-risk > 0, use the same plan and CSV path throughout:
|
||||
|
||||
If `vlm` is not on PATH, prefix commands with `uv run`.
|
||||
1. `vlm review-plan --input <plan> --output <csv>`
|
||||
2. Human reviews CSV (modify decision or keep)
|
||||
3. `vlm apply-review --plan <plan> --csv <csv>` — **required even if no changes** (writes `review_applied_at`)
|
||||
4. `vlm execute --plan <plan>` (dry-run with updated plan)
|
||||
5. Get explicit user confirmation
|
||||
6. `vlm execute --plan <plan> --confirm --require-review --review-csv <csv>`
|
||||
|
||||
## Preflight Checks
|
||||
Three rejection paths: missing CSV, missing `review_applied_at`, CSV path mismatch.
|
||||
|
||||
Run these checks before executing workflow commands:
|
||||
## Workflow Phases
|
||||
|
||||
1. Confirm current working directory is repository root.
|
||||
2. Probe command availability: `vlm --help` or `uv run vlm --help`.
|
||||
3. Run the target subcommand `--help` when options are uncertain.
|
||||
4. Confirm config validity with `vlm config validate` after config edits.
|
||||
5. Verify required input artifacts exist under `artifacts/` (or paths passed via flags).
|
||||
6. Treat `execute --confirm` as destructive and require explicit user confirmation.
|
||||
| Phase | Purpose | Artifact |
|
||||
|-------|---------|----------|
|
||||
| config | Set `library_root` | `~/.vlm/config.yaml` |
|
||||
| scan | Discover files | `inventory.csv` |
|
||||
| parse | Extract identities | `identities.json` |
|
||||
| enrich | Add TMDB metadata | `identities.json` (updated) |
|
||||
| analyze | Detect gaps/duplicates | `analysis.json` |
|
||||
| plan | Generate operations | `plan.json` |
|
||||
| review-plan | Export high-risk + preview | `plan_manual_review.csv` |
|
||||
| apply-review | Sync manual decisions | `plan.json` (updated) |
|
||||
| execute | Dry-run, then confirm | rollback log |
|
||||
| rollback | Revert if needed | restored files |
|
||||
|
||||
## Execution Rules
|
||||
## Decision Rules
|
||||
|
||||
Follow these rules while executing tasks:
|
||||
**duplicate_keep strategies** (5): `by_quality`, `by_reputation`, `by_reputation_quality_time`, `first_seen`, `manual`.
|
||||
|
||||
1. Prefer read-only stages first: scan, parse, enrich, analyze, plan.
|
||||
2. Treat `artifacts/plan.json` as the reviewable contract; summarize counts and conflicts before execution.
|
||||
3. Run `review-plan` and `apply-review` before `execute --confirm` when manual decisions are required.
|
||||
4. Run dry-run (`vlm execute`) before `vlm execute --confirm`.
|
||||
5. If execution is interrupted or results are incorrect, locate rollback logs and run `vlm rollback`.
|
||||
6. Keep outputs explicit in responses: file path, record counts, and next command.
|
||||
7. If the user asks for a partial workflow, run only required stages and state skipped dependencies.
|
||||
8. Before `execute --confirm`, run `vlm review-plan` and report high-risk counts; pause if the user has not reviewed high-risk operations.
|
||||
**Parser boundary risks**: filenames with resolution-like `1920x1080`/`1440x1080` and `Sample` clips are high-risk; require review-plan output before confirmation.
|
||||
|
||||
## Decision Points
|
||||
**Metadata quality**: prefer `vlm parse --inventory` when duplicate quality ranking matters.
|
||||
|
||||
Use these decision policies:
|
||||
|
||||
1. Duplicate handling: choose `plan.duplicate_keep` (`by_quality`, `by_reputation`, `by_reputation_quality_time`, `first_seen`, `manual`) per user preference.
|
||||
2. Enrichment: skip `vlm enrich` only when translations/reputation are not needed or API keys are unavailable.
|
||||
3. Metadata quality: prefer `vlm parse --inventory artifacts/inventory.csv` when duplicate quality ranking matters.
|
||||
4. Analysis-assisted planning: prefer `vlm plan --analysis artifacts/analysis.json` for automatic duplicate quarantine decisions.
|
||||
5. Parser boundary risk: treat resolution-like tokens (`1920x1080`) and `Sample` clips as high-risk; require review-plan output before confirmation.
|
||||
**Analysis-assisted planning**: prefer `vlm plan --analysis` for automatic duplicate quarantine.
|
||||
|
||||
## Output Contract
|
||||
|
||||
Return concise, operational summaries:
|
||||
|
||||
1. Commands executed.
|
||||
2. Artifacts generated or updated (under `artifacts/` by default).
|
||||
3. Key counts (files scanned, identities parsed, duplicate groups, plan operations).
|
||||
4. Risk counts from `review-plan` (manual_review / sample_source / high_season / high_episode / conflicts).
|
||||
5. Blocking errors and exact remediation command.
|
||||
6. Safe next step.
|
||||
|
||||
## Developer Verification
|
||||
|
||||
When modifying VLM core logic:
|
||||
|
||||
1. **Full suite**: `uv run pytest -q`
|
||||
2. **Core components**: `uv run pytest tests/test_scanner.py tests/test_planner.py tests/test_executor.py`
|
||||
3. **Property tests**: `uv run pytest tests/test_analysis_properties.py`
|
||||
4. **Lint** (with dev extras): `uv run ruff check src tests`
|
||||
1. Commands executed and artifacts generated.
|
||||
2. Key counts (files, identities, duplicates, operations).
|
||||
3. Risk counts from review-plan; blocking errors with exact remediation command.
|
||||
|
||||
## References
|
||||
|
||||
Load these references on demand:
|
||||
|
||||
1. `references/command-recipes.md` — command syntax, artifact expectations, failure triage.
|
||||
2. `references/workflow.md` — end-to-end operator workflow.
|
||||
3. `references/cli-reference.md` — command and config quick reference.
|
||||
4. `references/dev-guide.md` — architecture and developer modification patterns.
|
||||
- `references/triage.md`: failure triage mapping + preflight checks.
|
||||
- `references/dev-map.md`: module → test → verification mapping.
|
||||
- For CLI options: run `vlm <command> --help`. Do not trust memory.
|
||||
|
||||
@@ -1,31 +0,0 @@
|
||||
# Documentation Status
|
||||
- Updated to current CLI options on 2026-06-01. Default artifact paths are under `artifacts/`.
|
||||
|
||||
# VLM CLI Reference
|
||||
|
||||
## Configuration
|
||||
- `vlm config init`: Create default config.
|
||||
- `vlm config show`: Display current settings.
|
||||
- `vlm config validate`: Check config for errors.
|
||||
|
||||
## Core Commands
|
||||
- `vlm scan [--output PATH]`: Discover video files.
|
||||
- `vlm parse [--input CSV] [--output JSON] [--inventory CSV]`: Parse filenames.
|
||||
- `vlm enrich [--input JSON] [--output JSON] [--refresh-all]`: Fetch TMDB metadata.
|
||||
- `vlm analyze [--input JSON] [--output JSON]`: Find gaps and duplicates.
|
||||
- `vlm plan [--input JSON] [--analysis JSON] [--output JSON]`: Generate operations.
|
||||
- `vlm review-plan [--input JSON] [--output CSV] [--tui]`: Export manual review CSV (optional Textual UI).
|
||||
- `vlm apply-review [--plan JSON] [--csv PATH]`: Sync edited review CSV into plan.
|
||||
- `vlm execute [--plan JSON] [--confirm] [--yes] [--verbose-ops] [--safe-mode] [--preserve-directories]`: Move/Rename/Quarantine operations with safety guards.
|
||||
- `vlm rollback [--log PATH]`: Undo operations.
|
||||
|
||||
## Management & Reporting
|
||||
- `vlm quarantine list|add|restore`: Manage the `.quarantine` directory.
|
||||
- `vlm report inventory|completeness|duplicates|summary`: Generate human-readable reports.
|
||||
- `vlm state show|set|query|clear`: Track manual review status for files.
|
||||
|
||||
## Important Config Options (`~/.vlm/config.yaml`)
|
||||
- `library_root`: Path to the video collection.
|
||||
- `templates`: Naming patterns for movies and series.
|
||||
- `plan.duplicate_keep`: Strategy for duplicates (`by_quality`, `by_reputation`, `by_reputation_quality_time`, `first_seen`, `manual`).
|
||||
- `enrichment.api_keys`: TMDB and OpenAI keys.
|
||||
@@ -1,67 +0,0 @@
|
||||
# Documentation Status
|
||||
- Synced with artifacts/ baseline on 2026-06-01.
|
||||
|
||||
# VLM Command Recipes
|
||||
|
||||
## Baseline
|
||||
|
||||
Run from repository root unless the user specifies otherwise.
|
||||
|
||||
```bash
|
||||
vlm --help
|
||||
vlm config show
|
||||
vlm config validate
|
||||
```
|
||||
|
||||
If `vlm` is not on PATH:
|
||||
|
||||
```bash
|
||||
uv run vlm --help
|
||||
uv run vlm config show
|
||||
uv run vlm config validate
|
||||
```
|
||||
|
||||
## End-to-End Pipeline
|
||||
|
||||
Default artifact paths match CLI defaults under `artifacts/`:
|
||||
|
||||
```bash
|
||||
vlm scan
|
||||
vlm parse --inventory artifacts/inventory.csv
|
||||
vlm enrich
|
||||
vlm analyze --inventory artifacts/inventory.csv
|
||||
vlm plan --analysis artifacts/analysis.json
|
||||
vlm review-plan --input artifacts/plan.json --output artifacts/plan_manual_review.csv
|
||||
vlm apply-review
|
||||
vlm execute
|
||||
vlm execute --confirm
|
||||
```
|
||||
|
||||
## Artifact Expectations
|
||||
|
||||
1. `artifacts/inventory.csv` — discovered files with filesystem and optional ffprobe metadata.
|
||||
2. `artifacts/identities.json` — parsed identities (v2 when parse used `--inventory`).
|
||||
3. `artifacts/analysis.json` — completeness gaps and duplicate groups.
|
||||
4. `artifacts/plan.json` — planned operations (`move`, `rename`, `quarantine`, `no-op`).
|
||||
5. `artifacts/plan_manual_review.csv` — high-risk rows for human review before `--confirm`.
|
||||
|
||||
Do not commit these files to Git.
|
||||
|
||||
## Focused Workflows
|
||||
|
||||
```bash
|
||||
vlm parse --inventory artifacts/inventory.csv
|
||||
vlm analyze --input artifacts/identities.json --output artifacts/analysis.json --inventory artifacts/inventory.csv
|
||||
vlm plan --input artifacts/identities.json --analysis artifacts/analysis.json --output artifacts/plan.json
|
||||
vlm rollback
|
||||
```
|
||||
|
||||
## Frequent Failure Triage
|
||||
|
||||
1. Missing config: `vlm config init`, set `library_root`.
|
||||
2. Invalid config: `vlm config validate`.
|
||||
3. Missing input artifact: run prerequisite stage (scan → parse → analyze → plan).
|
||||
4. Unexpected duplicate decisions: check `plan.duplicate_keep`, rerun `vlm plan --analysis artifacts/analysis.json`.
|
||||
5. Unsafe execution: `vlm rollback`, re-run `review-plan` / `apply-review`.
|
||||
6. `vlm` not found: use `uv run vlm ...`.
|
||||
7. TMDB rate limits: lower `enrichment.max_concurrency` in config and retry later.
|
||||
@@ -1,33 +0,0 @@
|
||||
# Documentation Status
|
||||
- Updated for the modular command architecture on 2026-02-16.
|
||||
|
||||
# VLM Developer Guide
|
||||
|
||||
## Project Structure
|
||||
- `src/vlm/cli.py`: Entry point and thin command wrappers.
|
||||
- `src/vlm/parser.py`: Regex-based filename parsing logic.
|
||||
- `src/vlm/enrichment.py`: Pipeline for external metadata fetching.
|
||||
- `src/vlm/providers/`: API implementations (e.g., TMDB).
|
||||
- `src/vlm/planner.py`: Logic for mapping identities to filesystem operations.
|
||||
- `src/vlm/executor.py`: Safe file manipulation and rollback logging.
|
||||
|
||||
## Adding a New Command
|
||||
1. Create a new module in `src/vlm/commands/`.
|
||||
2. Define the command using `@click.command()`.
|
||||
3. Register it in `src/vlm/cli.py` with a Click-decorated function that delegates to the module implementation.
|
||||
|
||||
## Modifying the Parser
|
||||
- The parser uses a sequence of regex patterns in `src/vlm/parser.py`.
|
||||
- Add new patterns to the `PATTERNS` list or improve existing ones.
|
||||
- Always run `pytest tests/test_parser.py` after changes.
|
||||
|
||||
## Data Models
|
||||
See `src/vlm/models.py` for core data structures:
|
||||
- `VideoFile`: Basic file metadata.
|
||||
- `MovieIdentity` / `SeriesIdentity`: Parsed/enriched identity records.
|
||||
- `FileOperation`: Definition of a move/rename/quarantine/no-op/preserve-directory operation.
|
||||
|
||||
## Testing
|
||||
- **Unit Tests**: `pytest`
|
||||
- **Property-based Tests**: `pytest tests/test_analysis_properties.py` (uses Hypothesis).
|
||||
- **Integration Tests**: `pytest tests/test_reports_integration.py`.
|
||||
@@ -0,0 +1,25 @@
|
||||
# Developer Map
|
||||
|
||||
## Module → Test → Verification
|
||||
|
||||
| Module | Tests | When to run |
|
||||
|--------|-------|-------------|
|
||||
| `scanner.py` | `tests/test_scanner.py` | File discovery, metadata extraction |
|
||||
| `parser.py` | `tests/test_parser.py` | Filename parsing changes |
|
||||
| `enrichment.py`, `providers/` | `tests/test_enrichment.py` | TMDB/API changes |
|
||||
| `planner.py` | `tests/test_planner.py` | Operation generation, duplicate resolution |
|
||||
| `executor.py` | `tests/test_executor.py` | File operations, rollback |
|
||||
| `plan_review.py` | `tests/test_plan_review.py` | Review gate, CSV handling |
|
||||
| `commands/*.py` | `tests/test_cli_*.py` | CLI flag/behavior changes |
|
||||
| `analysis.py` | `tests/test_analysis_properties.py` | Property-based tests (Hypothesis) |
|
||||
| Full integration | `pytest` | Before any commit |
|
||||
|
||||
## Adding a New Command
|
||||
|
||||
1. Create module in `src/vlm/commands/`.
|
||||
2. Define with `@click.command()`.
|
||||
3. Import and register in `src/vlm/cli.py` via `main.add_command(...)`.
|
||||
|
||||
## Key Models
|
||||
|
||||
See `src/vlm/models.py`: `VideoFile`, `MovieIdentity`, `SeriesIdentity`, `FileOperation`, `ExecutionPlan`.
|
||||
@@ -0,0 +1,23 @@
|
||||
# Triage & Preflight
|
||||
|
||||
## Preflight Checks
|
||||
|
||||
Before executing workflow commands:
|
||||
|
||||
1. Confirm working directory is repository root.
|
||||
2. Run `vlm --help`; if unavailable, switch to `uv run vlm`.
|
||||
3. Run `<subcommand> --help` when options are uncertain.
|
||||
4. Run `vlm config validate` after config edits.
|
||||
5. Verify required input files exist before downstream stages.
|
||||
6. Treat `execute --confirm` as destructive; require explicit user confirmation.
|
||||
|
||||
## Failure Triage
|
||||
|
||||
| Problem | Command |
|
||||
|---------|---------|
|
||||
| Missing config | `vlm config init`, then set `library_root` |
|
||||
| Invalid config values | `vlm config validate` and fix reported keys |
|
||||
| Missing input artifact | Run prerequisite stage (scan → parse → analyze → plan) |
|
||||
| Unexpected duplicate decisions | Check `plan.duplicate_keep` in config, rerun `vlm plan --analysis` |
|
||||
| Unsafe execution results | `vlm rollback`, inspect plan, re-run `execute --confirm` |
|
||||
| `vlm` not found | Use `uv run vlm ...` fallback |
|
||||
@@ -1,74 +0,0 @@
|
||||
# Documentation Status
|
||||
- Synced with artifacts/ baseline on 2026-06-01.
|
||||
|
||||
# VLM Workflow Guide
|
||||
|
||||
This guide details the standard end-to-end process for organizing a video library using VLM.
|
||||
|
||||
## 1. Setup and Discovery
|
||||
|
||||
### Initialize Configuration
|
||||
```bash
|
||||
vlm config init
|
||||
```
|
||||
Edit `~/.vlm/config.yaml` to set `library_root` and optionally `workspace_dir: artifacts`.
|
||||
|
||||
### Library Scan
|
||||
```bash
|
||||
vlm scan
|
||||
```
|
||||
- **Goal**: Create `artifacts/inventory.csv`.
|
||||
- **Note**: Ensure `ffprobe` is installed for resolution and codec metadata.
|
||||
|
||||
## 2. Identification
|
||||
|
||||
### Filename Parsing
|
||||
```bash
|
||||
vlm parse --inventory artifacts/inventory.csv
|
||||
```
|
||||
- **Goal**: Create `artifacts/identities.json`.
|
||||
- **Why --inventory?**: Embeds video metadata (v2 schema) required for quality-based duplicate resolution.
|
||||
|
||||
### Metadata Enrichment
|
||||
```bash
|
||||
vlm enrich
|
||||
```
|
||||
- **Goal**: Update `artifacts/identities.json` with TMDB data.
|
||||
- **Troubleshooting**: Check `enrichment.api_keys` in config; never commit `~/.vlm/config.yaml`.
|
||||
|
||||
## 3. Analysis and Planning
|
||||
|
||||
### Detect Issues
|
||||
```bash
|
||||
vlm analyze
|
||||
```
|
||||
- **Goal**: Create `artifacts/analysis.json`.
|
||||
- **Outputs**: Episode gaps and duplicate groups.
|
||||
|
||||
### Create Execution Plan
|
||||
```bash
|
||||
vlm plan --analysis artifacts/analysis.json
|
||||
```
|
||||
- **Goal**: Create `artifacts/plan.json`.
|
||||
- **Strategy**: Uses `plan.duplicate_keep` (default: `by_reputation`) for duplicate decisions.
|
||||
|
||||
## 4. Review and Execution
|
||||
|
||||
### Human review
|
||||
```bash
|
||||
vlm review-plan
|
||||
# Optional: vlm review-plan --tui (requires textual extra)
|
||||
vlm apply-review # after editing artifacts/plan_manual_review.csv
|
||||
```
|
||||
|
||||
### Execute Changes
|
||||
```bash
|
||||
vlm execute # Dry-run
|
||||
vlm execute --confirm # Actual operations (explicit confirmation)
|
||||
```
|
||||
|
||||
### Reverting Changes
|
||||
```bash
|
||||
vlm rollback
|
||||
```
|
||||
Restores files using the latest log in `~/.vlm/rollback/`.
|
||||
Reference in New Issue
Block a user