windyboy
dfa18ed405
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.
70 lines
3.0 KiB
Markdown
70 lines
3.0 KiB
Markdown
---
|
|
name: vlm-library-workflow
|
|
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
|
|
|
|
## Safety Contract
|
|
|
|
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.
|
|
|
|
## Execution Threshold Semantics
|
|
|
|
- `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.
|
|
|
|
## High-Risk Closed Loop
|
|
|
|
When high-risk > 0, use the same plan and CSV path throughout:
|
|
|
|
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>`
|
|
|
|
Three rejection paths: missing CSV, missing `review_applied_at`, CSV path mismatch.
|
|
|
|
## Workflow Phases
|
|
|
|
| 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 |
|
|
|
|
## Decision Rules
|
|
|
|
**duplicate_keep strategies** (5): `by_quality`, `by_reputation`, `by_reputation_quality_time`, `first_seen`, `manual`.
|
|
|
|
**Parser boundary risks**: filenames with resolution-like `1920x1080`/`1440x1080` and `Sample` clips are high-risk; require review-plan output before confirmation.
|
|
|
|
**Metadata quality**: prefer `vlm parse --inventory` when duplicate quality ranking matters.
|
|
|
|
**Analysis-assisted planning**: prefer `vlm plan --analysis` for automatic duplicate quarantine.
|
|
|
|
## Output Contract
|
|
|
|
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
|
|
|
|
- `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.
|