Files

T

windyboy dfa18ed405 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.

2026-09-25 13:50:09 +08:00

3.0 KiB

Raw Blame History

name, description

name	description
vlm-library-workflow	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

Before execute --confirm, always run review-plan and report High-risk operations count.
If high-risk > 0: stop, wait for explicit user decision.
--confirm requires --require-review to enforce review gate; default does not force.
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:

vlm review-plan --input <plan> --output <csv>
Human reviews CSV (modify decision or keep)
vlm apply-review --plan <plan> --csv <csv> — required even if no changes (writes review_applied_at)
vlm execute --plan <plan> (dry-run with updated plan)
Get explicit user confirmation
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

Commands executed and artifacts generated.
Key counts (files, identities, duplicates, operations).
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.

3.0 KiB Raw Blame History