# 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