test: add real subtitle verification lane

docs/plans/2026-03-06-subtitle-sync-verification.md

@@ -0,0 +1,121 @@
+# Subtitle Sync Verification Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Replace the no-op `test:subtitle` lane with real automated subtitle-sync verification that reuses the maintained subsync tests and documents the real contributor workflow.
+
+**Architecture:** Repoint the subtitle verification command at the existing source-level subsync tests instead of inventing a second hidden suite. Add one focused ffsubsync failure-path test so the subtitle lane explicitly covers both engines plus a non-happy path, then update contributor docs to describe the dedicated subtitle lane and how it relates to `test:core`.
+
+**Tech Stack:** TypeScript, Bun test, Node test/assert, npm package scripts, Markdown docs.
+
+---
+
+### Task 1: Lock subtitle lane to real subsync tests
+
+**Files:**
+
+- Modify: `package.json`
+
+**Step 1: Write the failing test**
+
+Define the intended command shape first: `test:subtitle:src` should run `src/core/services/subsync.test.ts` and `src/subsync/utils.test.ts`, `test:subtitle` should invoke that real source lane, and no placeholder echo should remain.
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun run test:subtitle`
+Expected: It performs a build and prints `Subtitle tests are currently not configured`, proving the lane is still a no-op.
+
+**Step 3: Write minimal implementation**
+
+Update `package.json` so:
+
+- `test:subtitle:src` runs `bun test src/core/services/subsync.test.ts src/subsync/utils.test.ts`
+- `test:subtitle` runs the new source lane directly
+- `test:subtitle:dist` is removed if it is no longer the real verification path
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun run test:subtitle`
+Expected: PASS with Bun executing the real subtitle-sync test files.
+
+### Task 2: Add explicit ffsubsync non-happy-path coverage
+
+**Files:**
+
+- Modify: `src/core/services/subsync.test.ts`
+- Test: `src/core/services/subsync.test.ts`
+
+**Step 1: Write the failing test**
+
+Add a test that runs `runSubsyncManual({ engine: 'ffsubsync' })` with a stub ffsubsync executable that exits non-zero and writes stderr, then assert:
+
+- `result.ok === false`
+- `result.message` starts with `ffsubsync synchronization failed`
+- the failure message includes command details surfaced to the user
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test src/core/services/subsync.test.ts`
+Expected: FAIL because ffsubsync failure propagation is not asserted yet.
+
+**Step 3: Write minimal implementation**
+
+Keep production code unchanged unless the new test exposes a real bug. If needed, tighten failure assertions or message propagation in `src/core/services/subsync.ts` without changing successful behavior.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test src/core/services/subsync.test.ts`
+Expected: PASS with both alass and ffsubsync paths covered, including a non-happy path.
+
+### Task 3: Make contributor docs match the real verification path
+
+**Files:**
+
+- Modify: `README.md`
+- Modify: `package.json`
+
+**Step 1: Write the failing test**
+
+Use the repository state as the failure signal: README currently advertises subtitle sync as a feature but does not tell contributors that `bun run test:subtitle` is the real verification lane.
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun run test:subtitle && bun test src/subsync/utils.test.ts`
+Expected: Tests pass, but docs still do not explain the lane; this is the remaining acceptance-criteria gap.
+
+**Step 3: Write minimal implementation**
+
+Update `README.md` with a short contributor-facing verification note that:
+
+- points to `bun run test:subtitle` for subtitle-sync coverage
+- states that the lane reuses the maintained subsync tests already included in broader core coverage
+- avoids implying there is a separate hidden subtitle test harness beyond those tests
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun run test:subtitle`
+Expected: PASS, with docs and scripts now aligned around the same subtitle verification strategy.
+
+### Task 4: Verify matrix integration stays clean
+
+**Files:**
+
+- Modify: `package.json` (only if Task 1/3 exposed cleanup needs)
+
+**Step 1: Write the failing test**
+
+Treat duplication as the failure condition: confirm the dedicated subtitle lane reuses the same maintained files already present in `test:core:src` rather than creating a second divergent suite.
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun run test:subtitle && bun run test:core:src`
+Expected: If file lists diverge unexpectedly, this review step exposes it before handoff.
+
+**Step 3: Write minimal implementation**
+
+If needed, do the smallest script cleanup necessary so subtitle coverage remains explicit without hiding or duplicating existing core coverage.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun run test:subtitle && bun run test:core:src`
+Expected: PASS, confirming the dedicated lane and the broader core suite agree on subtitle coverage.