video_translate/docs/plans/2026-03-18-alignment-fallback-safety.md

Alignment Fallback Safety Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Stop subtitle generation from silently falling back into the Studio project workflow unless an explicit environment flag enables it.

Architecture: Keep the existing alignment adapter and Studio fallback code path, but gate that fallback behind a parsed boolean config from .env. When the alignment endpoint returns 404 or 405 and the flag is not enabled, fail fast with a clear error instead of returning unrelated subtitles.

Tech Stack: TypeScript, Vitest, Express, Node fetch/FormData APIs

---

Task 1: Add failing tests for safe-by-default fallback behavior

Files:

• Modify: E:/Downloads/ai-video-dubbing-&-translation/src/server/alignmentAdapter.test.ts
• Modify: E:/Downloads/ai-video-dubbing-&-translation/src/server/audioPipelineConfig.test.ts
• Modify: E:/Downloads/ai-video-dubbing-&-translation/src/server/subtitleGeneration.test.ts

Step 1: Write the failing tests

• Add a test asserting requestAlignedTranscript() throws a clear error on 404 when Studio fallback is not explicitly enabled.
• Update the existing fallback test to pass only when allowStudioProjectFallback is set to true.
• Add config tests for parsing ALLOW_STUDIO_PROJECT_FALLBACK with a default of false.
• Add a pipeline test asserting generateSubtitlePipeline() forwards the parsed fallback flag into requestAlignedTranscript().

Step 2: Run targeted tests to verify they fail

Run: node ./node_modules/vitest/vitest.mjs run src/server/alignmentAdapter.test.ts src/server/audioPipelineConfig.test.ts src/server/subtitleGeneration.test.ts

Expected: FAIL because the fallback flag does not exist yet and requestAlignedTranscript() still auto-falls back.

Task 2: Implement the minimal fallback gate

Files:

• Modify: E:/Downloads/ai-video-dubbing-&-translation/src/server/audioPipelineConfig.ts
• Modify: E:/Downloads/ai-video-dubbing-&-translation/src/server/alignmentAdapter.ts
• Modify: E:/Downloads/ai-video-dubbing-&-translation/src/server/subtitleGeneration.ts

Step 1: Add config parsing

• Extend AudioPipelineConfig with allowStudioProjectFallback: boolean.
• Parse ALLOW_STUDIO_PROJECT_FALLBACK from .env, defaulting to false.

Step 2: Gate fallback execution

• Extend RequestAlignedTranscriptOptions with allowStudioProjectFallback.
• When the alignment root returns 404 or 405 and the flag is false, throw a clear error that points to ALLOW_STUDIO_PROJECT_FALLBACK=true or a proper alignment backend.
• When the flag is true, keep the current Studio project workflow unchanged.

Step 3: Thread config through the pipeline

• Pass allowStudioProjectFallback from resolveAudioPipelineConfig() into requestAlignedTranscript() inside generateSubtitlePipeline().

Task 3: Update docs and verify

Files:

• Modify: E:/Downloads/ai-video-dubbing-&-translation/.env.example
• Modify: E:/Downloads/ai-video-dubbing-&-translation/README.md

Step 1: Document the new flag

• Add ALLOW_STUDIO_PROJECT_FALLBACK="false" to .env.example.
• Clarify in README.md that subtitle generation now uses the local Studio workflow by default, and that fail-fast mode is opt-in.

Step 2: Run verification

Run: node ./node_modules/vitest/vitest.mjs run src/server/alignmentAdapter.test.ts src/server/audioPipelineConfig.test.ts src/server/subtitleGeneration.test.ts Expected: PASS

Run: node ./node_modules/vitest/vitest.mjs run Expected: PASS

Run: cmd /c npm run lint Expected: PASS