epic: restore transcript and shell integration contracts #191

Completion status — 2026-10-15

Completed and merged into main via #281, commit 27952c9e9818ab38829278fa9712e8e121878aad. The observable-result checklist below is updated to reflect the delivered scope and recorded decisions. Final integrated main aaca138d7c3773be662941b4081c8d97ea40019c passed post-merge CI. Final local verification passed pnpm validate, 5,895 frontend/API tests, and five policy-record tests. Browser E2E was skipped.

#270 remains open as a separately scoped, nonblocking live-provider investigation. No provider spend was authorized or performed.

Epic branch: epic/191-transcript-shell. Plan checkpoint 4 of 7.

Why

#187 and #155 merged with component and in-memory tests that missed the schema, remount, and lifecycle boundaries where they fail: generated captions are rejected by the operation schema, a replaced transcript keeps a stale word selection, the chat dock can lose or duplicate its first prompt, the automation scope event can precede the dock mount, and onboarding overwrites a saved plan-mode choice.

Evidence is in 01-findings.md. The sequencing is in 02-development-plan.md. The lessons behind it are in LESSONS.md and 03-lessons-and-contributors.md.

Observable result

• Generated captions round-trip through the real operation schema, HTTP request, persist, reload, undo, and redo without losing timing or source anchors (R1).
• Replacing a source transcript clears the selection. Mounting the same transcript keeps it (R2).
• The dock sends the initial prompt exactly once across close, slow load, navigation, and reopen (R3).
• Automation category and scoped answers survive dock mounting and submission (R4).
• Setup reruns preserve explicit plan-mode settings (R5).
• Any new UI text exists in all six locales.

Sub-issues

• fix(video-ir): caption operation schema accepts the fields the compiler emits (R1) #211 fix(video-ir): caption operation schema accepts the fields the compiler emits (R1)
• fix(video): replacing a source transcript clears the word selection (R2) #212 fix(video): replacing a source transcript clears the word selection (R2)
• fix(chat-dock): deliver the first prompt exactly once across close, slow load, and navigation (R3) #213 fix(chat-dock): deliver the first prompt exactly once across close, slow load, and navigation (R3)
• fix(automation): scope event waits for the dock and carries its category (R4) #214 fix(automation): scope event waits for the dock and carries its category (R4) (blocked by fix(chat-dock): deliver the first prompt exactly once across close, slow load, and navigation (R3) #213)
• fix(onboarding): setup reruns preserve an explicit plan-mode setting (R5) #215 fix(onboarding): setup reruns preserve an explicit plan-mode setting (R5)
• decide: empty-caption restore, translation budget, and fork cost semantics #216 decide: empty-caption restore, translation budget, and fork cost semantics
• fix(video-ir): restore captions beside unrelated empty tracks #268 fix(video-ir): restore captions beside unrelated empty tracks (follow-up from decide: empty-caption restore, translation budget, and fork cost semantics #216)
• docs(video): align caption translation cost claims with behavior #269 docs(video): align caption translation cost claims with behavior (follow-up from decide: empty-caption restore, translation budget, and fork cost semantics #216)

Sub-issues without a blocker can run in parallel, each in its own worktree: #211, #212, #213, #215, #216.

Deferred follow-up outside completed implementation

• test(claude): verify inherited fork cost with a live SDK trace #270 remains open pending explicit authorization for live provider spend and credentials. This is an unconfirmed accounting investigation, not a confirmed billing defect. Per its recorded scope, no implementation is blocked on it. It has not been run and is not marked complete.

How this epic is worked

1. The maintainer creates epic/191-transcript-shell from main and pushes it. Nobody commits to it directly.
2. Each sub-issue is implemented by one agent in its own git worktree on issue/<n>-<slug>, opened as a PR whose base is epic/191-transcript-shell and whose body contains Closes #<sub-issue>.
3. A merged sub-issue PR closes its issue through .github/workflows/epic-close-issues.yml. Sub-issues merge by squash, one commit each.
4. When every sub-issue above is closed, open one epic PR from epic/191-transcript-shell into main with Closes #191. Run pnpm validate, pnpm test:fast (naming the known resolve.test.ts failure until it is fixed), and the surface checks for this epic on the final head, and write that head sha in the PR.
5. The maintainer reviews and merges the epic PR. No sub-issue PR targets main.

Shared files that two streams must not edit at once are package.json, pnpm-lock.yaml, locale modules, component-size-allowlist.json, http-daemon.ts, video-edit-server.ts, and the shared video IR schemas. Each sub-issue names the files it owns and what it is blocked by. If you need a file another open sub-issue owns, comment on both issues and wait.

Suggested merge order into main across epics is E1 first, so later epic PRs run the repaired gate, then the rest by priority. Rebase an epic branch onto main before its final PR.