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

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.