@su-record/vibe 2.9.24 → 2.9.32

package/skills/vibe-test/SKILL.md

@@ -1,247 +1,140 @@
----
-name: vibe-test
-tier: core
-description: "Self-test vibe across CC and coco. Subcommands: parity (static file/content comparison between ~/.claude and ~/.coco install dirs), report (runtime invocation of every command/skill/hook/agent/tool in the current harness), compare (diff two JSON reports). P1 drift (one-side missing) auto-registers via vibe-regress. Must use this skill when user runs /vibe.test, when verifying multi-harness compatibility before release, or when the user says 'parity', 'self-test', 'CC vs coco', 'both harnesses'."
-triggers: [test, parity, self-test, "양쪽", "CC vs coco", "harness 동일"]
-priority: 70
-chain-next: []
----
-
-# vibe-test — Multi-Harness Self-Test
-
-**Purpose**: mechanically verify vibe presents the same surface in Claude Code and coco. Catch features broken on one harness before users do.
-
-## Why this exists
-
-Vibe explicitly supports two harnesses (CC, coco). When new commands are added, only one side might get updated, or `AGENTS.md` ↔ `CLAUDE.md` may drift, and there is no automated check until a user reports it. This skill closes that gap.
-
-## Storage Contract
-
-```
-.claude/vibe/test-reports/    # CC side artifacts
-.coco/vibe/test-reports/      # coco side artifacts (when run from coco)
-
-  <YYYYMMDD-HHmm>-cc.json     # machine-comparable
-  <YYYYMMDD-HHmm>-cc.md       # human summary
-  <YYYYMMDD-HHmm>-coco.json
-  <YYYYMMDD-HHmm>-coco.md
-  <YYYYMMDD-HHmm>-parity.json # output of `parity` subcommand
-  <YYYYMMDD-HHmm>-compare.md  # output of `compare` subcommand
-```
-
-### Report schema (JSON)
-
-```json
-{
-  "harness": "cc | coco",
-  "version": "2.9.21",
-  "timestamp": "2026-04-14T18:30:00+09:00",
-  "vibe-version": "from package.json",
-  "commands": [
-    { "name": "vibe.spec", "loaded": true, "first-response-ok": true, "error": null }
-  ],
-  "skills": [
-    { "name": "vibe-spec", "trigger-recognized": true, "context-injected": true, "error": null }
-  ],
-  "hooks": [
-    { "name": "pre-tool-guard", "test-suite": "passed | failed", "tests": "32/32" }
-  ],
-  "agents": [],
-  "tools": []
-}
-```
-
-## Subcommand: `parity` — static comparison (stage 1, in-scope target)
-
-No harness execution. Only file system + body inspection. Fast and deterministic.
-
-### Steps
-
-1. **Confirm both install dirs exist**:
-   - CC: `~/.claude/{commands,skills,agents}/`
-   - coco: `~/.coco/{commands,skills,agents}/` (`COCO_HOME` env takes precedence)
-   - If either side is missing, exit cleanly with guidance (not an error)
-
-2. **Install set diff**:
-   ```bash
-   find ~/.claude/commands -type f -name '*.md' -exec basename {} \; | sort > /tmp/cc-cmds
-   find ~/.coco/commands -type f -name '*.md' -exec basename {} \; | sort > /tmp/coco-cmds
-   diff /tmp/cc-cmds /tmp/coco-cmds
-   ```
-   Repeat for skills/agents. Persist diff entries to `parity.json` field `install-set-diff`.
-
-3. **Content sync (CLAUDE.md ↔ AGENTS.md)**:
-   - Read both files; strip header block (leading `> ` lines plus filename mentions)
-   - Normalize body: map `.claude` ↔ `.coco`, `Claude Code` ↔ `coco`, `CLAUDE.md` ↔ `AGENTS.md`
-   - Lines that still differ after normalization go into `content-drift`
-
-4. **Path reference validation**:
-   - Extract `~/.claude/`, `.claude/vibe/` patterns from CLAUDE.md → confirm each resolves under the actual install dir
-   - Extract `~/.coco/`, `.coco/vibe/` patterns from AGENTS.md → same check
-   - Wrong paths (e.g. AGENTS.md referencing `.codex/` after a rename) classified as `path-error`
-
-5. **Console output**:
-   ```
-   📊 PARITY REPORT
-
-   Install set:
-     ✅ commands: 14/14 matched
-     ❌ skills: 1 missing in coco (vibe-test)
-
-   Content sync:
-     ✅ CLAUDE.md ↔ AGENTS.md normalized diff: clean
-
-   Path references:
-     ✅ all paths resolve to existing dirs
-
-   📈 Parity Score: 95/100
-   📁 Saved: .claude/vibe/test-reports/20260414-1830-parity.json
-   ```
-
-6. **Auto-register P1 drift**:
-   - On `install-set-diff` finding → call `/vibe.regress register --from-test`
-   - symptom: `"Parity drift: <category> missing in <harness>"`
-   - root-cause-tag: `integration`
-
-## Subcommand: `report` — runtime invocation
-
-Inspect every shipped feature in the current harness, capture pass/fail, and emit the JSON+MD report defined above.
-
-### Probe philosophy
-
-- **No external LLM calls.** The probe is structural + execution-based, not generative. Cost ≈ a few file reads plus running `vitest`.
-- **Interactive commands are NOT actually invoked.** Calling `/vibe.spec` would block on the interview loop. Probe checks structural validity only and records `invocable: true` if the file is well-formed.
-- **Hooks and tools have real unit tests** in the repo — run them, do not simulate.
-- A probe failure never stops the run. Each entry's `error` field captures the cause; the report keeps going.
-
-### Steps
-
-1. **Resolve install dir for current harness**:
-   - CC: `~/.claude/`
-   - coco: `~/.coco/` (`COCO_HOME` overrides)
-   - Detect via `process.env.COCO_HOME` first, then which one is currently being read from. If both present, use the harness this skill was invoked from.
-
-2. **Probe `commands`** — for each `<install>/commands/*.md`:
-   - `loaded`: file exists and is non-empty
-   - `frontmatter-valid`: YAML frontmatter parses; required keys present (`description`)
-   - `argument-hint-present`: optional but recorded
-   - `body-references-skill`: body contains `Load skill ` or `## Process` (signal that the command delegates correctly)
-   - Result: `{ name, loaded, frontmatter-valid, body-references-skill, error }`
-
-3. **Probe `skills`** — for each `<install>/skills/*/SKILL.md`:
-   - `loaded`: file exists
-   - `frontmatter-valid`: YAML parses with required keys: `name`, `tier`, `description`, `triggers`
-   - `triggers-non-empty`: triggers array has ≥1 entry
-   - `description-mentions-trigger-conditions`: heuristic — description contains `Must use this skill when` or equivalent (vibe convention)
-   - Result: `{ name, loaded, frontmatter-valid, triggers-count, error }`
-
-4. **Probe `hooks`** — for each `<install>/hooks/scripts/*.js` (or repo `hooks/scripts/` if testing the source):
-   - If a matching `__tests__/<hook-name>.test.js` exists → run `npx vitest run hooks/scripts/__tests__/<hook>.test.js --reporter=json` and parse the result
-   - If no test exists → mark `test-suite: "no-tests"` (warn, not fail)
-   - Result: `{ name, test-suite: "passed" | "failed" | "no-tests", tests: "<passed>/<total>", error }`
-
-5. **Probe `agents`** — for each `<install>/agents/*.md`:
-   - `loaded`, `frontmatter-valid` (required: `name`, `description`, `tools`)
-   - `tools-list-valid`: every tool in the `tools` array matches a known harness tool (Read, Glob, Grep, Bash, Edit, Write, WebSearch, WebFetch, Task, plus the agent-specific Skill etc.)
-   - Result: `{ name, loaded, frontmatter-valid, tools-list-valid, error }`
-
-6. **Probe `tools`** — for each tool exported from `dist/tools/index.js`:
-   - If a matching test file exists in `src/tools/__tests__/` → run vitest and capture pass/fail
-   - If no test → call the tool with a minimal known-safe input (e.g. `validateCodeQuality` against a tiny fixture) and verify the response is well-shaped JSON
-   - Result: `{ name, test-suite | smoke-call, status, error }`
-
-7. **Compile JSON + Markdown reports** to `<project-vibe-dir>/test-reports/<YYYYMMDD-HHmm>-<harness>.{json,md}` per the schema above.
-
-8. **Print summary**:
-   ```
-   📊 RUNTIME REPORT (cc)
-     commands: 14/14 loaded, 14/14 frontmatter-valid
-     skills:   28/28 loaded, 1 missing description-mentions-trigger-conditions
-     hooks:    7/7 test suites passed (118/118 tests)
-     agents:   42/42 loaded, 0 with invalid tools
-     tools:    9/9 passing
-   📈 Score: 99/100
-   📁 .claude/vibe/test-reports/20260414-1845-cc.json
-   ```
-
-### Failure handling
-
-| Probe failure | Action |
-|---|---|
-| frontmatter parse error | record + continue |
-| missing required key | record + continue |
-| vitest run failure | capture stderr summary into `error` field, continue |
-| tool smoke-call exception | record exception type + continue |
-| install dir not found | abort with clear message — cannot probe what is not installed |
-
-### What this catches
-
-- A new command added in source but missed by `postinstall` (file present in repo, absent from `~/.claude/commands/`)
-- Skill with malformed frontmatter (would fail to register at runtime)
-- Agent listing a tool that does not exist in the harness
-- Hook unit test regression (matches existing CI guard but locally observable)
-- Tool that broke between the test fixture and the shipped build
-
-### What this does NOT catch
-
-- LLM behavioral drift (interactive command actually behaving differently)
-- Race conditions in agent orchestration
-- Real-world failures that depend on user input
-
-These belong to higher-effort future work (functional e2e, currently not in scope).
-
-## Subcommand: `compare` — diff two reports
-
-```
-/vibe.test compare <cc-report.json> <coco-report.json>
-```
-
-### Steps
-
-1. Load both JSON files. Compare timestamps; warn if delta > ±1 minute ("report timing skew detected, confidence low")
-2. Match entries per category by `name`
-3. Classify:
-   - **P1**: present on only one side → missing
-   - **P2**: present both sides but mismatched booleans (`loaded`, `first-response-ok`, `trigger-recognized`) → behavioral drift
-   - **P3**: only error wording differs, behavior identical → informational
-4. Persist result as `<ts>-compare.md`
-5. P1 findings auto-register via `/vibe.regress`
-
-## Integration Points
-
-### Release flow
-
-Recommended pre-release ritual:
-```
-1. From CC:   /vibe.test parity → must pass
-2. From coco: /vibe.test parity → must pass (when feasible)
-3. Both green → pnpm release
-```
-
-### To /vibe.regress
-
-On P1 drift:
-```
-Load skill `vibe-regress` with:
-  subcommand: register --from-test
-  symptom: "<category> drift: <name> missing in <harness>"
-  root-cause-tag: integration
-```
-
-## Done Criteria
-
-### Subcommand: parity
-- [ ] Works without any external calls
-- [ ] Missing one install dir → clean exit with guidance (not an error)
-- [ ] `install-set-diff`, `content-drift`, `path-error` reported as separate categories
-- [ ] P1 findings invoke `/vibe.regress` automatically
-- [ ] `compare` handles timing-skew warning correctly
-
-### Subcommand: report
-- [ ] No external LLM calls (cost = file reads + vitest runs only)
-- [ ] Interactive commands probed structurally, never actually invoked
-- [ ] Hook and tool tests run via real vitest, not simulated
-- [ ] A probe failure on one entry never stops the run
-- [ ] JSON report matches the schema in "Storage Contract"
-- [ ] Markdown summary printed to console after run completes
-- [ ] Install dir absent → abort with clear message (not silent)
+---
+name: vibe-test
+tier: core
+description: "Self-test vibe by probing every command/skill/hook/agent in a target harness install dir (~/.claude or ~/.coco) and writing a pass/fail report to ~/.vibe/test-reports/. Takes an optional harness argument (cc|coco); empty = current harness. Must use this skill when user runs /vibe.test, when verifying a vibe install before release, or when the user says 'self-test', 'harness 점검', 'vibe 건강'."
+triggers: [test, self-test, "vibe 건강", "harness 점검", "자가검진"]
+priority: 70
+chain-next: []
+---
+
+# vibe-test — Self-Test
+
+Probe every shipped vibe surface in one install dir and emit a pass/fail report.
+
+## Why this exists
+
+When vibe ships new commands, skills, hooks, or agents, one side (CC or coco) can end up out of sync with the other, frontmatter can drift, and hook tests can silently break. `/vibe.test` is the single mechanical check: does every surface in the target install actually load and pass its own tests?
+
+## Target harness
+
+The argument selects which install dir to probe:
+
+| Arg | Probed dir |
+|---|---|
+| (empty) | current harness — CC: `~/.claude/`, coco: `~/.coco/` |
+| `cc` | `~/.claude/` |
+| `coco` | `~/.coco/` |
+
+If the target dir does not exist, print a clear message and exit with guidance (not an error). Example:
+
+```
+~/.coco/ not found — coco isn't installed on this machine.
+  To install: pnpm add -g @su-record/vibe-coco
+```
+
+## Probes
+
+All probes are **structural or test-based** — no interactive command is ever actually invoked, and no LLM is called.
+
+| Category | Source | Check |
+|---|---|---|
+| commands | `<install>/commands/*.md` | file readable · frontmatter parses · `description` present · body references a skill (`Load skill \`...\``) if it delegates |
+| skills | `<install>/skills/*/SKILL.md` | frontmatter parses · required fields (`name`, `description`) · `triggers` array non-empty · body non-empty |
+| hooks | repo `hooks/scripts/*.js` | for each script with a matching `__tests__/<name>.test.js`, run `npx vitest run <test> --reporter=json` and parse pass/fail counts |
+| agents | `<install>/agents/*.md` | file readable · frontmatter parses · required fields (`name`, `description`) |
+
+A probe's failure is captured in its `error` field; the overall run never halts because of one failure.
+
+## Report template
+
+Written to `~/.vibe/test-reports/<YYYYMMDD-HHmm>-<harness>.{json,md}`. Exact schema:
+
+### JSON
+
+```json
+{
+  "harness": "cc",
+  "timestamp": "2026-04-16T18:30:00+09:00",
+  "vibe_version": "2.9.24",
+  "install_dir": "/Users/grove/.claude",
+  "summary": {
+    "total": 42,
+    "passed": 40,
+    "failed": 2
+  },
+  "probes": {
+    "commands": [
+      { "name": "vibe.spec", "status": "pass" },
+      { "name": "vibe.test", "status": "pass" }
+    ],
+    "skills": [
+      { "name": "vibe-test", "status": "pass" },
+      { "name": "vibe-spec", "status": "fail", "error": "frontmatter: triggers array is empty" }
+    ],
+    "hooks": [
+      { "name": "pre-tool-guard", "status": "pass", "tests": "38/38" },
+      { "name": "keyword-detector", "status": "pass", "tests": "12/12" }
+    ],
+    "agents": [
+      { "name": "explorer", "status": "pass" }
+    ]
+  },
+  "failed": [
+    {
+      "category": "skills",
+      "name": "vibe-spec",
+      "error": "frontmatter: triggers array is empty"
+    }
+  ]
+}
+```
+
+- `status`: `"pass"` | `"fail"`
+- `error`: required when `status === "fail"`, omitted otherwise
+- `tests` (hooks only): short `passed/total` string from the vitest JSON reporter
+- `failed[]`: flat list of every failure for quick scanning — mirrors entries found across `probes.*`
+
+### Markdown
+
+```markdown
+# vibe self-test · cc · 2026-04-16 18:30
+
+**Version**: 2.9.24   **Install**: /Users/grove/.claude
+
+| Category | Pass | Fail |
+|---|---:|---:|
+| commands | 15 | 0 |
+| skills   | 17 | 1 |
+| hooks    |  6 | 0 |
+| agents   |  3 | 1 |
+| **total**| **41** | **2** |
+
+## Failures
+
+- **skills / vibe-spec** — frontmatter: triggers array is empty
+- **agents / explorer** — agent file not found
+```
+
+If `failed` is empty, replace the Failures section with `_All probes passed._`.
+
+## Steps
+
+1. **Resolve target**: argument (`cc` / `coco` / empty). Empty → detect current harness (`$CLAUDE_PROJECT_DIR` set → `cc`; else fall back to `cc`).
+2. **Resolve install dir**: `cc` → `~/.claude`, `coco` → `~/.coco`. If missing → print guidance + exit.
+3. **Read `vibe_version`** from `package.json` in the current repo.
+4. **Walk each category**, run its check, append `{ name, status, error? }` to `probes.<category>`.
+5. **Compute** `summary` counts and the flat `failed[]` list.
+6. **Ensure** `~/.vibe/test-reports/` exists (`mkdir -p`, dir mode `0o700` — consistent with `~/.vibe/config.json`).
+7. **Write** `<ts>-<harness>.json` and `<ts>-<harness>.md`.
+8. **Print** the Markdown summary to the console.
+9. **If `summary.failed > 0`**, load skill `vibe-regress` with `subcommand: register --from-test` and pass the failed entries. P1 = any probe with `status: fail`.
+
+## Done Criteria
+
+- [ ] No external LLM call — file reads + vitest runs only
+- [ ] One probe failing never halts the overall run
+- [ ] Target install dir missing → clean exit with guidance (not an error)
+- [ ] JSON report matches the template above exactly (fields, types, naming)
+- [ ] Markdown summary printed to console after the run
+- [ ] Reports land in `~/.vibe/test-reports/`, never in project-local `.claude/vibe/`
+- [ ] `failed.length > 0` → auto-invokes `/vibe.regress register --from-test`

package/skills/video-production/SKILL.md

@@ -1,52 +1,52 @@
----
-name: video-production
-tier: standard
-description: "Video processing gotchas — FFmpeg commands, transcoding pipelines, HLS/DASH streaming setup, subtitle embedding (SRT/VTT), and thumbnail extraction. Use when the project involves any video manipulation, media processing, or streaming infrastructure. Covers codec selection, bitrate optimization, and common FFmpeg pitfalls. Must use this skill when user works with video files, mentions FFmpeg, or needs media processing — even for simple tasks like 'generate a thumbnail'."
-triggers: [video, ffmpeg, transcode, encode, stream, media, subtitle, thumbnail, hls, dash]
-priority: 60
----
-
-# Video Production
-
-## Pre-check (K1)
-
-> Are you processing video files programmatically? If just embedding a YouTube/Vimeo player, this skill is not needed.
-
-## Gotchas
-
-| Gotcha | Consequence | Prevention |
-|--------|-------------|------------|
-| Direct CLI string concatenation | Command injection risk | Always use wrapper library (fluent-ffmpeg for TS, ffmpeg-python for Python) |
-| No input validation | Crash on corrupted files | Always `ffprobe` input before processing — check codec, resolution, duration |
-| No temp file cleanup | Disk fills up silently | `try/finally` or cleanup handler — never leave partial outputs |
-| No progress callback | Long encoding appears frozen | Implement progress events for any operation >10s |
-| Memory loading large files | OOM on 4K+ video | Use streaming I/O, never read entire file into memory |
-| Assuming codec availability | Fails on different FFmpeg builds | Check `ffmpeg -codecs` at runtime before encoding |
-| Fixed bitrate encoding | Inconsistent quality | Use CRF-based quality (18-28 for H.264) instead |
-| No timeout | Encoding hangs forever | Set timeout + kill process on expiry |
-
-## Codec Quick Reference
-
-| Use Case | Codec | Note |
-|----------|-------|------|
-| Maximum compatibility | H.264 (libx264) | CRF 23 default |
-| Smaller files | H.265 (libx265) | 50% smaller, slower, licensing issues |
-| Open source | VP9 (libvpx-vp9) | Good for WebM |
-| Best compression | AV1 (libaom-av1) | Very slow encoding |
-
-## Resolution Presets
-
-| Preset | Resolution | Bitrate (H.264) |
-|--------|-----------|-----------------|
-| 360p | 640x360 | 800 kbps |
-| 720p | 1280x720 | 3 Mbps |
-| 1080p | 1920x1080 | 6 Mbps |
-| 4K | 3840x2160 | 15 Mbps |
-
-## Done Criteria (K4)
-
-- [ ] All FFmpeg calls go through wrapper library (no raw CLI strings)
-- [ ] Input files validated with ffprobe before processing
-- [ ] Temp files cleaned up in all paths (success + error)
-- [ ] Progress reporting for long operations
-- [ ] Codec availability checked at runtime
+---
+name: video-production
+tier: standard
+description: "Video processing gotchas — FFmpeg commands, transcoding pipelines, HLS/DASH streaming setup, subtitle embedding (SRT/VTT), and thumbnail extraction. Use when the project involves any video manipulation, media processing, or streaming infrastructure. Covers codec selection, bitrate optimization, and common FFmpeg pitfalls. Must use this skill when user works with video files, mentions FFmpeg, or needs media processing — even for simple tasks like 'generate a thumbnail'."
+triggers: [video, ffmpeg, transcode, encode, stream, media, subtitle, thumbnail, hls, dash]
+priority: 60
+---
+
+# Video Production
+
+## Pre-check (K1)
+
+> Are you processing video files programmatically? If just embedding a YouTube/Vimeo player, this skill is not needed.
+
+## Gotchas
+
+| Gotcha | Consequence | Prevention |
+|--------|-------------|------------|
+| Direct CLI string concatenation | Command injection risk | Always use wrapper library (fluent-ffmpeg for TS, ffmpeg-python for Python) |
+| No input validation | Crash on corrupted files | Always `ffprobe` input before processing — check codec, resolution, duration |
+| No temp file cleanup | Disk fills up silently | `try/finally` or cleanup handler — never leave partial outputs |
+| No progress callback | Long encoding appears frozen | Implement progress events for any operation >10s |
+| Memory loading large files | OOM on 4K+ video | Use streaming I/O, never read entire file into memory |
+| Assuming codec availability | Fails on different FFmpeg builds | Check `ffmpeg -codecs` at runtime before encoding |
+| Fixed bitrate encoding | Inconsistent quality | Use CRF-based quality (18-28 for H.264) instead |
+| No timeout | Encoding hangs forever | Set timeout + kill process on expiry |
+
+## Codec Quick Reference
+
+| Use Case | Codec | Note |
+|----------|-------|------|
+| Maximum compatibility | H.264 (libx264) | CRF 23 default |
+| Smaller files | H.265 (libx265) | 50% smaller, slower, licensing issues |
+| Open source | VP9 (libvpx-vp9) | Good for WebM |
+| Best compression | AV1 (libaom-av1) | Very slow encoding |
+
+## Resolution Presets
+
+| Preset | Resolution | Bitrate (H.264) |
+|--------|-----------|-----------------|
+| 360p | 640x360 | 800 kbps |
+| 720p | 1280x720 | 3 Mbps |
+| 1080p | 1920x1080 | 6 Mbps |
+| 4K | 3840x2160 | 15 Mbps |
+
+## Done Criteria (K4)
+
+- [ ] All FFmpeg calls go through wrapper library (no raw CLI strings)
+- [ ] Input files validated with ffprobe before processing
+- [ ] Temp files cleaned up in all paths (success + error)
+- [ ] Progress reporting for long operations
+- [ ] Codec availability checked at runtime

package/skills/video-production/rubrics/quality-checklist.md

@@ -1,58 +1,58 @@
-# Video Quality Checklist
-
-## Pre-Processing
-
-- [ ] Input file exists and is readable before pipeline starts
-- [ ] `ffprobe` run on input — codec, resolution, duration, bitrate logged
-- [ ] Corrupted/truncated files rejected with clear error (not crash)
-- [ ] Input resolution within supported range (min 360p, max 4K)
-- [ ] Audio stream present — handle gracefully if missing
-
-## Encoding
-
-- [ ] CRF-based encoding used (not fixed bitrate) for consistent visual quality
-- [ ] Target codec available in current FFmpeg build (`ffmpeg -codecs` check)
-- [ ] Encoding runs through wrapper library — no raw CLI string concatenation
-- [ ] `-movflags +faststart` set for MP4 (enables streaming before full download)
-- [ ] Audio normalized: loudness target -16 LUFS (streaming standard)
-- [ ] Aspect ratio preserved — no unintended stretching
-
-## Progress & Monitoring
-
-- [ ] Progress events emitted for any operation exceeding 10 seconds
-- [ ] Encoding timeout configured — process killed on expiry
-- [ ] Estimated time remaining shown in progress (based on bitrate processed)
-
-## Output Validation
-
-- [ ] Output file exists after encoding completes
-- [ ] Output duration verified: within ±2 seconds of input
-- [ ] Output codec matches requested codec (re-run ffprobe on output)
-- [ ] Output file size within acceptable range (flag if >3x input size)
-- [ ] Thumbnail: correct dimensions, not blank/corrupted
-
-## Subtitles (if applicable)
-
-- [ ] Subtitle file encoding is UTF-8 (convert if needed)
-- [ ] Subtitle timing verified — first/last cue in range of video duration
-- [ ] Burn-in subtitles visually tested on dark and light scenes
-
-## HLS / DASH Streaming (if applicable)
-
-- [ ] `.m3u8` manifest references correct segment file names
-- [ ] All segment files present in output directory
-- [ ] Segment duration consistent (target ±1 second of configured value)
-- [ ] CORS headers configured on media server
-
-## Storage & Cleanup
-
-- [ ] Temp directory cleaned in `finally` block — both success and error paths
-- [ ] No partial output files left on disk after failure
-- [ ] Output written to separate directory from temp files
-- [ ] Disk space checked before processing large files (minimum 3x input size free)
-
-## Security
-
-- [ ] Input file path sanitized — no directory traversal (`../`)
-- [ ] FFmpeg invoked via array arguments (not shell string) to prevent injection
-- [ ] Max file size limit enforced before processing begins
+# Video Quality Checklist
+
+## Pre-Processing
+
+- [ ] Input file exists and is readable before pipeline starts
+- [ ] `ffprobe` run on input — codec, resolution, duration, bitrate logged
+- [ ] Corrupted/truncated files rejected with clear error (not crash)
+- [ ] Input resolution within supported range (min 360p, max 4K)
+- [ ] Audio stream present — handle gracefully if missing
+
+## Encoding
+
+- [ ] CRF-based encoding used (not fixed bitrate) for consistent visual quality
+- [ ] Target codec available in current FFmpeg build (`ffmpeg -codecs` check)
+- [ ] Encoding runs through wrapper library — no raw CLI string concatenation
+- [ ] `-movflags +faststart` set for MP4 (enables streaming before full download)
+- [ ] Audio normalized: loudness target -16 LUFS (streaming standard)
+- [ ] Aspect ratio preserved — no unintended stretching
+
+## Progress & Monitoring
+
+- [ ] Progress events emitted for any operation exceeding 10 seconds
+- [ ] Encoding timeout configured — process killed on expiry
+- [ ] Estimated time remaining shown in progress (based on bitrate processed)
+
+## Output Validation
+
+- [ ] Output file exists after encoding completes
+- [ ] Output duration verified: within ±2 seconds of input
+- [ ] Output codec matches requested codec (re-run ffprobe on output)
+- [ ] Output file size within acceptable range (flag if >3x input size)
+- [ ] Thumbnail: correct dimensions, not blank/corrupted
+
+## Subtitles (if applicable)
+
+- [ ] Subtitle file encoding is UTF-8 (convert if needed)
+- [ ] Subtitle timing verified — first/last cue in range of video duration
+- [ ] Burn-in subtitles visually tested on dark and light scenes
+
+## HLS / DASH Streaming (if applicable)
+
+- [ ] `.m3u8` manifest references correct segment file names
+- [ ] All segment files present in output directory
+- [ ] Segment duration consistent (target ±1 second of configured value)
+- [ ] CORS headers configured on media server
+
+## Storage & Cleanup
+
+- [ ] Temp directory cleaned in `finally` block — both success and error paths
+- [ ] No partial output files left on disk after failure
+- [ ] Output written to separate directory from temp files
+- [ ] Disk space checked before processing large files (minimum 3x input size free)
+
+## Security
+
+- [ ] Input file path sanitized — no directory traversal (`../`)
+- [ ] FFmpeg invoked via array arguments (not shell string) to prevent injection
+- [ ] Max file size limit enforced before processing begins