re-edit

いつ使うか（必ず発火する条件）

• ユーザーが「もう少し短くして」「この部分カットして」「順番を変えて」と言ったとき
• 既存 rough cut に対して局所修正を入れたいとき
• 05_timeline/timeline.json が既に存在し、patch apply で再編集できるとき
• review_patch.json を人間指示から直接作り直して再 compile したいとき

前提条件

• 05_timeline/timeline.json が存在すること
• 06_review/review_patch.json は schemas/review-patch.schema.json に従うこと
• runtime/compiler/patch.ts の allowed op は以下のみ
  • replace_segment
  • trim_segment
  • move_segment
  • insert_segment
  • remove_segment
  • change_audio_policy
  • change_visual_transform
  • change_audio_finish
  • add_marker
  • add_note
• review_patch.json.timeline_version には timeline.json.version を入れること
• scripts/compile-timeline.ts --patch ... は timeline.json を上書きし、preview-manifest.json を再生成し、最後に schema validation を走らせる
• current 実装では patch mode の --fps は使われない。fps を変えたい場合は upstream compile 側を見直す
• replace_segment / insert_segment は unsafe になりやすい。必要なら review-roughcut/references/patch-patterns.md も参照すること

やること（ステップ）

Step 0: 修正面を canonical router で確定する

人間の指示を直接 review_patch.json や project-local script にしない。最初に次を実行する。

npm run caption-edit-route -- --project projects/<project> --instruction "<human instruction>" --reviewer "<reviewer>" --write-receipt

分岐は3つだけ:

• caption_review_patch: 字幕本文・改行・表示timing。caption-review.ts の init/edit/retime/apply/approveへ進む。
• caption_visual_treatment: style、size、rect、hierarchy、emphasis、animation。下記のvisual-only previewへ進む。
• timeline_review_patch: shot order、trim、crop/reframe、audio。従来どおり 06_review/review_patch.jsonへ進む。

status=hold、route=null、または複数routeを含む指示では、routerが書く 06_review/caption-edit-route.json だけをdegraded-route noteとして残して停止する。 勝手に複数patchへ分解せず、project-local ASS/FFmpeg/render scriptを書かない。

caption draft / approval が欠ける場合、routerの project.initialize_commands にあるcanonical commandを順に使う。 代表経路は次のとおり。approve は全字幕の人間確認後だけ実行し、自動承認しない。

npx tsx scripts/caption-review.ts prepare --project projects/<project>
npx tsx scripts/caption-review.ts init --project projects/<project> --reviewer "<reviewer>"
npx tsx scripts/caption-review.ts approve --project projects/<project> --reviewer "<reviewer>"

Step 1: ユーザーの修正指示を patchable な意図に落とす

• 何を短く / 削除 / 入れ替え / 調整したいのかを具体化する
• request が local patch で済むか、selects / blueprint / package の更新が要るかを先に切る
• 詳細な自然言語マッピングは references/edit-commands.md を参照すること

Step 2: 現在の timeline を読む

• 05_timeline/timeline.json の version を確認する
• 対象 clip の clip_id, segment_id, beat_id, role, timeline_in_frame, timeline_duration_frames を確認する
• 置換や挿入が必要なら 04_plan/selects_candidates.yaml と、必要に応じて 06_review/human_notes.yaml を読む

Step 3: patch で直せるかを判断する

patch で直せる代表例:

• クリップを少し短くする
• 冗長なクリップを削除する
• 既存クリップの順番や入る frame をずらす
• approved candidate に差し替える
• nat sound / ducking / fade を局所調整する
• 人物のzoom/crop/positionを変更する
• タイムライン全体へ会話MAプリセットを指定する

patch だけでは不正確な代表例:

• approved source や anchor のない新規シーン追加
• beat の再設計が必要な大きな並べ替え
• BGM asset 自体の差し替え

後者は無理に patch 化せず、必要なら select-clips / build-blueprint / render-video 側へ回す。

Step 4: 06_review/review_patch.json を生成する

基本 shape:

{
  "timeline_version": "<timeline.json version>",
  "operations": []
}

• op 名は schema にあるものだけを使う
• 1 op = 1 つの具体的修正
• target_clip_id / with_segment_id / new_timeline_in_frame / new_src_in_us など、必要 field を実データから埋める
• reason は必須。可能なら confidence と evidence も入れる

Step 5: patch を適用して再 compile する

npx tsx scripts/compile-timeline.ts projects/<project> --patch projects/<project>/06_review/review_patch.json

selects / blueprint を直したあとの full compile が必要なら別途 compile mode を使う。

npx tsx scripts/compile-timeline.ts projects/<project> --fps 30

Step 6: 結果を確認する

• Patch errors: が出ていないか
• timeline.json.version が increment されたか
• 05_timeline/preview-manifest.json が再生成されたか
• Schema validation: PASSED になったか

Step 7: 必要なら render をやり直す

• ユーザーが final packaged video まで求めており、Gate 10 を満たしているなら render-video を実行する
• rough cut の再編集だけなら timeline.json / preview manifest の更新で止める

Caption visual-only authoring + preview

caption_visual_treatment の場合、production approvalを変更せず、1 commandでpatch authoringとpreapproval previewを作る。 初回は --expected-patch-hash absent、2回目以降は直前結果の patch_hash を使う。 --expected-approval-hash はrouter出力の project.caption_approval_binding_hash を使う。

npx tsx scripts/caption-review.ts visual-author-preview --project projects/<project> --reviewer "<reviewer>" --typography-policy projects/<project>/04_plan/typography_policy.json --visual-operation-json '<schema-valid operation JSON>' --expected-patch-hash <hash-or-absent> --expected-approval-hash <caption-approval-binding-hash>

出力は patch_path/hash、input_path/hash、preview_output_path/hash、preapproval receipt_path/hash、caption identity、before/after text_timing_hash、before/after approval hashを返す。 両hashが不変で production_approval_unchanged=true の場合だけpreview候補として扱う。 stale hash/receipt、unknown field、project外path、blocked / human_hold はfail closedで停止する。 顔相対rectはsubject evidenceが無ければverifiedにせずdegradedで停止する。

speech captionの本文・timing・描画ownerはcaption review/finalize + FFmpeg/libass。 graphical hook/title/emphasisのownerはregistered content element + Remotion。 同一文言・重複時間の二重ownerはpreflight rejectし、未登録templateを生成しない。

canonical rendererが表現不能な場合だけ、承認者・15分以内のtimestamp・production approval hashへbindした degraded-route-receipt/v1を用意し、repo-owned writerでreview-only outputを発行する: npm run project-output:degraded -- --project projects/<project> --source <review-file> --output projects/<project>/09_output/<versioned-review-file> --degraded-route-receipt projects/<project>/06_review/degraded-route-receipt.json receiptなし、架空command/capability/tool、承認者不一致、stale/future timestampでは書込み前に停止する。

出力 artifact

• 06_review/review_patch.json
• 05_timeline/timeline.json
• 05_timeline/preview-manifest.json
• 条件が揃っていて render まで進める場合は 07_package/*
• router: 06_review/caption-edit-route.json
• visual-only preview: 07_package/caption_visual_treatment_patch.json、 07_package/caption_visual_treatment_preapproval_input.json、 07_package/caption_visual_treatment_preapproval_receipt.json、 05_timeline/preview-baseline-fast-full.mp4と同previewのcanonical .receipt.json

注意事項

• reorder という patch op はない。現在の repo では並べ替えは主に move_segment で表現する
• change_audio_policy は ducking / nat sound / fade 調整であり、BGM asset の差し替えではない
• 「長くして」は move_segment / insert_segment / upstream blueprint 修正になることがある。duration を盲目的に伸ばさない
• MAまたは人物リフレームを含む場合は finish-interview を併用し、字幕や質問カードより前の映像レイヤーへ変換を適用する
• 講演・インタビューを信頼感のある縦型SNSショートへ仕上げる場合は finish-business-short を併用し、重複発言の削除、冒頭主張、フル字幕、 話者表記、登録済みCTA、retention QAを一体で扱う
• クリエイター・挑戦・Vlog・共感創出系の縦型SNSショートへ仕上げる場合は finish-creator-short を併用し、7-Beat構成、テンポ伸縮、パンチイン（zoom）、 要約キーワードテロップ、証拠素材インサート、SE同期、Platform BGM Handoffを一体で扱う
• patch mode は selects_candidates.yaml や edit_blueprint.yaml を自動更新しない