windy/dl-organizer
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

refactor: consolidate skill docs, add anti-drift tests, and apply audit fixes

Browse Source 
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
2026-09-25 13:50:09 +08:00
parent c7a55190d7
commit dfa18ed405
35 changed files with 1116 additions and 621 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/vlm-library-workflow/SKILL.md
+43 -70
View File
@@ -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.