Files
karaoke-gen/docs/archive/2026-11-19-review-ready-gate.md
T
Andrew Beveridge ☄️andClaude Opus 5.5 f4f0f6af77 feat(review): only show the review button once the job is fully prepared (v0.298.0) (#1273)
## Summary

The review button now appears only once a job is fully prepared: stems
separated, auto-approval re-scored with them, AI lyric corrections
generated and applied on the server, and review audio + waveforms
cached. The browser no longer applies AI corrections by itself, so there
is one code path.

Prompted by job ae995697 (a Made For You order): the review button
showed at 18:29, but the stems, backing verdict and vocal waveform only
existed from 18:32, and the server pre-apply had aborted on a
duplicate-word check, leaving the browser to apply corrections on load.

## Changes

- **Hold every job until stems land**
(`review_gate.route_after_scoring`). Before, only jobs whose lyrics
would auto-ship were held, so Made For You and lyrics-gated jobs opened
review early. Same kill switch (`AUTO_APPROVAL_AUDIO_HOLD_ENABLED`) and
20-minute backstop.
- **Generate AI suggestions on the API service before parking.** The
hold is released inside the audio-separation job, which has no LLM
credentials, so that job only applies an existing cache.
- **`enter_human_review` prepares everything before AWAITING_REVIEW**:
pre-apply (generating on a cache miss), then
`review_assets.prepare_review_assets` (OGG transcodes, backing waveform,
vocal peak envelope), then the transition.
- **Non-strict pre-apply for human review**
(`build_applied_segments(strict=False)`): what "Accept All" produces.
Stale/duplicate signals are recorded as `warnings`. The auto-ship path
stays strict.
- **Removed the browser's on-load auto-run/auto-apply** from
`useAutoCorrect`.
- **Job card shows "[5/10] Preparing review"** while held (new summary
field + 33 locales).
- Docs: ARCHITECTURE review-gate step,
`docs/archive/2026-11-19-review-ready-gate.md`.

Trade-off: Made For You and lyrics-gated jobs reach review (and send the
review-ready notification) ~3 minutes later.

## Testing

- Backend unit suite: 7294 passed. Locally failing: 8
emulator-integration tests (something unrelated listens on :8080 so they
don't skip; CI runs them against real emulators) and 1 locale test that
tripped on a gitignored translation snapshot (passes once removed).
- New/updated tests: review gate (review-verdict jobs held, kill switch,
prepare-before-transition order, suggestions generated before parking,
no double wait, missing job), non-strict apply, duplicate-word pre-apply
(ae995697 case), review_assets.
- Frontend Jest: 1834 passed; no type errors in touched files.
- Local CodeRabbit: 2 minor findings fixed, re-review clean.

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_012RYLVVdAxGitbw1FhYP4e4

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 16:12:58 -05:00

3.3 KiB

Review button only when the job is fully prepared (2026-11-19)

Ask

Andrew, after job ae995697 showed "Review Lyrics" while audio separation was still running:

i want the review button to only appear when a job is "fully prepared", including with the ai corrections and the lead vocal waveform images ready to load - and i don't like the different code paths implied by this statement; i want the ai corrections to always be processed before i open the review page: "The AI corrections are already ready when the button appears: either applied on the server, or applied by the page when it loads"

What was happening (job ae995697, a Made For You order)

UTC Event
18:28:44 Screens worker scored the job: lyrics review/phantom-gate, blockers made_for_you, audio_incomplete
18:29:01 Waited for AI suggestions, re-scored: still review, hold_for_audio=False → AWAITING_REVIEW (button shown)
18:29:01 Server pre-apply aborted (duplicate_words:ne,ne,ne,ne,ne), so the browser would apply on load
18:32:41 Stems landed; audio-worker re-score: backing with_backing

Two gaps:

  1. The review hold (gen #1232, 2026-10-29) only held jobs whose lyrics would auto-ship (executor.py hold_for_audio). Any job a human had to review anyway (every Made For You order, every lyrics-gated job) opened review before the stems, the backing verdict, the vocal waveform (/vocals-peaks) and the missing-lyrics markers existed.
  2. The server pre-apply used the auto-ship sanity gates (stale / duplicate-word aborts). On abort the browser ran its own auto-run + auto-apply on load: a second code path.

Change

  • Hold every job whose stems aren't ready when the screens worker finishes (review_gate.route_after_scoring), not just lyrics-auto ones. Kill switch unchanged (AUTO_APPROVAL_AUDIO_HOLD_ENABLED); 20-minute backstop unchanged.
  • AI suggestions are generated on the API service before parking: the hold is normally released inside the audio-separation job, which has no LLM credentials and AUTO_CORRECT_PROACTIVE_ENABLED unset, so it can only apply an existing cache.
  • enter_human_review prepares everything before AWAITING_REVIEW: pre-apply (generate on miss), then review_assets.prepare_review_assets (OGG transcodes, backing waveform from the backing-vocals stem, vocal peak envelope), then the transition.
  • Pre-apply for human review is non-strict (build_applied_segments(strict=False)): it produces what "Accept All" would, records stale/duplicate signals as warnings in metadata.auto_approval. The executor's auto-ship path stays strict.
  • The browser never auto-runs or auto-applies suggestions (useAutoCorrect autoRunOnLoad/autoApplyOnLoad and the on-load rebase removed). Without a server pre-apply (only if the LLM was down for both attempts) the review opens uncorrected and the AI panel can be run by hand.
  • Job card shows "[5/10] Preparing review" while held (auto_review_waiting_for_stems added to the job-list summary fields).

The late-stems polling in LyricsAnalyzer stays as a backstop for timeout releases.

Cost

Made For You and lyrics-gated jobs reach review ~3 minutes later (the separation tail), and their review-ready notification fires then too.