akari-video 0.1.10 → 0.1.12

package/bin/akari.mjs

@@ -10,6 +10,7 @@ import { runAcceptCommand } from '../src/accept-command.mjs';
 import { runCapabilityCommand } from '../src/capability-command.mjs';
 import { runStoreCommand } from '../src/store-command.mjs';
 import { runAssetsCommand } from '../src/assets-command.mjs';
+import { runMigrateCommand } from '../src/migrate-command.mjs';
 import { maybeApplyPendingUpdateOnLaunch, readOwnVersion } from '../src/update-check.mjs';
 import { describeCliHelp } from '../src/messages.mjs';
 
@@ -67,6 +68,7 @@ const invoke = (argv[0] === '--version' || argv[0] === '-v') ? printVersion()
   : argv[0] === 'capability' ? runCapabilityCommand(argv.slice(1))
   : argv[0] === 'store' ? runStoreCommand(argv.slice(1))
   : argv[0] === 'assets' ? runAssetsCommand(argv.slice(1))
+  : argv[0] === 'migrate' ? runMigrateCommand(argv.slice(1))
   : run(argv);
 
 const result = await invoke.catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "AKARI Video launcher CLI — start an AI-edited video project from any directory: scaffold, connection check, then hand over to Claude Code (or opencode). AKARI Video を opencode や Claude Code で、どのディレクトリからでも始めるための `akari` ランチャー CLI。接続確認（doctor）→ 未セットアップならプロジェクト雛形を作成 → AI エージェントを起動する。外部 npm 依存ゼロ（Node.js 組み込みモジュールのみ）。",
   "type": "module",
   "bin": {
@@ -37,6 +37,6 @@
   "scripts": {
     "prepack": "node scripts/prepack.mjs",
     "postpack": "node scripts/prepack.mjs clean",
-    "test": "node --test test/*.mjs"
+    "test": "node --test --test-concurrency=1 test/*.mjs"
   }
 }

package/src/messages.mjs

@@ -224,6 +224,7 @@ export function describeCliHelp() {
     '  sounds                 公式音源ライブラリを一括ダウンロード（無料）',
     '  update                 更新を確認する',
     '  status                 接続状態を確認する',
+    '  migrate [dir]          古い edit.json を退避バックアップ付きで v2 へ変換',
     '',
     '開発者向け:',
     '  --opencode              Claude Code の代わりに opencode を起動する',

package/src/migrate-command.mjs

@@ -0,0 +1,127 @@
+import { createRequire } from 'node:module';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { createInterface } from 'node:readline/promises';
+
+import { resolveLauncherAssets } from './repo-assets.mjs';
+
+const require = createRequire(import.meta.url);
+
+export async function runMigrateCommand(args, options = {}) {
+  const log = options.log ?? ((line) => console.log(line));
+  const error = options.error ?? ((line) => console.error(line));
+  const cwd = options.cwd ?? process.cwd();
+  const parsed = parseArguments(args, cwd);
+  if (!parsed.ok) {
+    error(parsed.message);
+    return { exitCode: 2 };
+  }
+  if (parsed.help) {
+    for (const line of migrateHelp()) log(line);
+    return { exitCode: 0 };
+  }
+  const projectRoot = parsed.projectRoot;
+  const editPath = path.join(projectRoot, 'edit.json');
+  let text;
+  try {
+    text = await (options.readFile ?? readFile)(editPath, 'utf8');
+  } catch (cause) {
+    error(`edit.json を読めません: ${editPath} (${messageOf(cause)})`);
+    return { exitCode: 2 };
+  }
+  const migrate = options.migrate ?? loadMigrateModule(options.assets ?? resolveLauncherAssets());
+  const proposal = migrate.planMigration(projectRoot, editPath, text, { now: options.now });
+  if (proposal.ok === false) {
+    if (parsed.json) {
+      log(JSON.stringify({ ok: false, error: 'このプロジェクトは変換できません', blockers: proposal.blockers }));
+    } else {
+      error('このプロジェクトは変換できません。');
+      for (const blocker of proposal.blockers) error(`- ${blocker}`);
+    }
+    return { exitCode: 2 };
+  }
+  if (parsed.json) {
+    log(JSON.stringify({
+      ok: true, dryRun: parsed.dryRun, version: proposal.version,
+      filePath: proposal.filePath, backupPath: proposal.backupPath, changes: proposal.changes
+    }));
+  } else {
+    log(`変換対象: ${proposal.filePath} (version ${proposal.version} -> 2)`);
+    for (const change of proposal.changes) log(`- ${change.path}: ${change.note}`);
+    log(`変換前の退避先: ${proposal.backupPath}`);
+  }
+  if (parsed.dryRun) {
+    if (!parsed.json) log('--dry-run のため、ファイルは変更しません。');
+    return { exitCode: 0, proposal };
+  }
+  if (!parsed.yes) {
+    const isTTY = options.isTTY ?? (process.stdin.isTTY && process.stdout.isTTY);
+    if (!isTTY) {
+      error('非 TTY では明示承認が必要です。内容を確認し、--yes を付けて再実行してください。');
+      return { exitCode: 2, proposal };
+    }
+    const accepted = options.confirm
+      ? await options.confirm()
+      : await promptForConfirmation();
+    if (!accepted) {
+      if (!parsed.json) log('変換しませんでした。edit.json は変更されていません。');
+      return { exitCode: 0, proposal };
+    }
+  }
+  await migrate.applyMigration(proposal);
+  if (!parsed.json) log(`version 2 へ変換しました。元ファイル: ${proposal.backupPath}`);
+  return { exitCode: 0, proposal };
+}
+
+function loadMigrateModule(assets) {
+  const modulePath = path.join(assets.repoRoot, 'packages', 'edit-store', 'lib', 'migrate', 'index.js');
+  try {
+    return require(modulePath);
+  } catch (cause) {
+    throw new Error(`変換器を読み込めません: ${modulePath} (${messageOf(cause)})`);
+  }
+}
+
+function parseArguments(args, cwd) {
+  const flags = new Set(args.filter(value => value.startsWith('-')));
+  const unknown = [...flags].filter(value => !['--yes', '-y', '--dry-run', '--json', '--help', '-h'].includes(value));
+  if (unknown.length > 0) return { ok: false, message: `未知のオプションです: ${unknown.join(', ')}` };
+  const positional = args.filter(value => !value.startsWith('-'));
+  if (positional.length > 1) return { ok: false, message: '引数のプロジェクトディレクトリは 1 つだけ指定できます。' };
+  return {
+    ok: true,
+    help: flags.has('--help') || flags.has('-h'),
+    yes: flags.has('--yes') || flags.has('-y'),
+    dryRun: flags.has('--dry-run'),
+    json: flags.has('--json'),
+    projectRoot: path.resolve(cwd, positional[0] ?? '.')
+  };
+}
+
+async function promptForConfirmation() {
+  const readline = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await readline.question('上記の内容で version 2 へ変換しますか? [y/N] ');
+    return /^(?:y|yes)$/iu.test(answer.trim());
+  } finally {
+    readline.close();
+  }
+}
+
+export function migrateHelp() {
+  return [
+    '使い方: akari migrate [dir] [--yes] [--dry-run] [--json]',
+    '',
+    'v0/v1 の edit.json を v2 へ片道変換します。',
+    '既定は変更内容を表示して y/n で確認し、変換前の全文を .akari/backup/ へ退避します。',
+    '',
+    '  --yes, -y   表示後の確認を省略',
+    '  --dry-run   提案の表示だけで書き込まない',
+    '  --json      機械可読な JSON を出力',
+    '  --help, -h  このヘルプを表示'
+  ];
+}
+
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/status-core/status.mjs

@@ -7,6 +7,7 @@ import { resolveProjectDisplayName } from "./display-name.mjs";
 import { inspectFullIntegrity } from "./integrity.mjs";
 import { validateAndCountReview } from "./review.mjs";
 
+
 export {
   detectStatusScope,
   resolveWorkspaceStatus,
@@ -218,30 +219,38 @@ function validatePlan(value, problems) {
 
 function validateEdit(value, problems) {
   if (!value) return;
-  if (value.version !== 0 && value.version !== 1) {
+  if (value.version !== 2) {
     problems.push(`edit.json has unsupported version ${String(value.version)}`);
     return;
   }
-  if (!isRecord(value.output) || !Array.isArray(value.overlays)) problems.push("edit.json has an invalid output/overlays shape");
-  if (value.version === 0) {
-    if (!isNonEmptyString(value.source?.path) || Object.hasOwn(value, "sources")) problems.push("edit.json v0 source shape is invalid");
-  } else {
-    if (!Array.isArray(value.sources) || Object.hasOwn(value, "source") || !Array.isArray(value.cuts)) {
-      problems.push("edit.json v1 sources/cuts shape is invalid");
+  if (!isRecord(value.output) || !Array.isArray(value.sources) || !Array.isArray(value.tracks)) {
+    problems.push("edit.json v2 has an invalid output/sources/tracks shape");
+    return;
+  }
+  const sourceIds = new Set();
+  for (const source of value.sources) {
+    if (!isNonEmptyString(source?.id) || !isNonEmptyString(source?.path) || sourceIds.has(source.id)) {
+      problems.push("edit.json v2 sources are invalid or duplicated");
       return;
     }
-    const ids = new Set();
-    for (const source of value.sources) {
-      if (!isNonEmptyString(source?.id) || !isNonEmptyString(source?.path) || ids.has(source.id)) {
-        problems.push("edit.json v1 sources are invalid or duplicated");
-        break;
-      }
-      ids.add(source.id);
+    sourceIds.add(source.id);
+  }
+  const trackIds = new Set();
+  for (const track of value.tracks) {
+    const hasItems = Array.isArray(track?.items);
+    const hasContent = isRecord(track?.content);
+    if (!isNonEmptyString(track?.id) || trackIds.has(track.id)
+      || (track?.lane !== "visual" && track?.lane !== "audio") || hasItems === hasContent) {
+      problems.push("edit.json v2 tracks are invalid or duplicated");
+      return;
     }
-    for (const cut of value.cuts) {
-      if (!isRecord(cut) || !ids.has(cut.src)) {
-        problems.push(`edit.json cut references unknown source ${String(cut?.src)}`);
-        break;
+    trackIds.add(track.id);
+    if (!hasItems) continue;
+    for (const item of track.items) {
+      if (!isRecord(item) || !isRecord(item.source)
+        || (item.source.kind === "media" && !sourceIds.has(item.source.src))) {
+        problems.push(`edit.json v2 item references unknown source ${String(item?.source?.src)}`);
+        return;
       }
     }
   }
@@ -270,14 +279,14 @@ function resolveMaterialState({ projectRoot, edit, interpretation, problems, war
   let fixed = false;
   if (edit) {
     fixed = true;
-    if (edit.version === 0 && isNonEmptyString(edit.source?.path)) {
-      sources = [resolveProjectPath(projectRoot, edit.source.path, "edit source", problems)];
-    } else if (edit.version === 1 && Array.isArray(edit.sources) && Array.isArray(edit.cuts)) {
-      const usedIds = new Set(edit.cuts.map((cut) => cut?.src));
-      sources = edit.sources
-        .filter((source) => usedIds.has(source.id))
-        .map((source) => resolveProjectPath(projectRoot, source.path, `edit source ${source.id}`, problems));
-    }
+    const mainVisualTrack = Array.isArray(edit.tracks)
+      ? edit.tracks.find(track => track?.lane === "visual" && Array.isArray(track.items)) : null;
+    const usedIds = new Set((mainVisualTrack?.items ?? [])
+      .filter(item => item?.source?.kind === "media")
+      .map(item => item.source.src));
+    sources = (Array.isArray(edit.sources) ? edit.sources : [])
+      .filter(source => usedIds.has(source?.id) && isNonEmptyString(source?.path))
+      .map(source => resolveProjectPath(projectRoot, source.path, `edit source ${source.id}`, problems));
   } else if (interpretation && Array.isArray(interpretation.inputs?.analyses)) {
     fixed = true;
     for (const [index, entry] of interpretation.inputs.analyses.entries()) {

package/vendor/.akari-capability-sources.json

@@ -39,6 +39,7 @@
     "docs/contract-2026-08-12-still-image-cut-source-v0.md",
     "docs/contract-2026-08-13-avatar-drive-v0.md",
     "docs/contract-2026-08-14-avatar-vrm-v0.md",
+    "docs/contract-2026-08-18-v1-render-parity.md",
     "packages/akari-launcher/package.json",
     "packages/akari-launcher/README.md",
     "packages/akari-tools/package.json",

package/vendor/docs/contract-2026-07-17-data-contract-versioning.md

@@ -64,3 +64,30 @@
 2. 「追加のみ進化・tolerant reader」を契約文書に明記する
 3. 破壊的変更時の変換手順を書く節を契約文書に確保する（bump するまで空でよい）
 4. 読み手の forward-compat 挙動（原則 3）を実装する
+
+## 5. 契約ファイル名の `-vN` と edit.json スキーマ版の語彙衝突（2026-08-18 追記）
+
+契約ファイル名の `-vN` サフィックス（例: `contract-2026-08-12-still-image-cut-source-v0.md`）は
+**その契約文書自身のリビジョン**であり、本書が定めるデータ契約の `version` フィールド
+（edit.json 等のスキーマ版）とは無関係である。両者は独立に増減する — 契約文書が改訂されても
+edit.json の `version` は変わらないし、edit.json が `version: 1` に上がっても関連契約が
+`-v1.md` へリネームされるわけではない。
+
+「still-image-cut-source-v0（契約の第 1 版）を読んで edit.json は v1（スキーマ版）で書く」の
+ような読み替えは誤読を招く。edit.json のスキーマ版に言及する契約文書は、本文冒頭で
+**「edit v0」「edit v1」の表記**を使い分け、ファイル名の `-vN` と区別できるようにする（例:
+「本契約は edit v1 の `sources[]` を対象とする」）。読み手（エージェント・人間）も、契約
+ファイル名の `-vN` を見て自動的にスキーマ版だと解釈しない。
+
+## 6. edit.json v0/v1 凍結変換器の終了方針（2026-08-18 オーナー裁定）
+
+- 変換器は機能追加禁止・バグ修正のみとする。未知の v0/v1 ケースに対応を
+  追加せず、「このプロジェクトは変換できません」と理由付きで止まる。
+- AKARI Video 本体から変換器を外す期限は、製品版 `1.0.0` の公開日または
+  `2026-12-31` のいずれか早い方とする。
+- 期限到達時は変換器を破棄せず、単体 npm パッケージ `akari-migrate` へ切り出して
+  1 回だけ publish し、以後更新しない。publish 自体は本移行タスクでは行わず、
+  本体から外す作業の一部とする。
+- 本体から外した後のエラー文言は次で固定する。
+
+  > このプロジェクトは古い形式です。`npx akari-migrate@<版> <dir>` で変換してから開いてください。

package/vendor/docs/contract-2026-07-22-render-basics.md

@@ -17,7 +17,7 @@
 |---|---|---|---|---|
 | 1 | 定速変更（クリップ単位の倍速/スロー） | `cuts[].speed`（number・既定 1.0・v0 は定速のみ、ランプは将来） | `setpts` + `atempo`（>2x/<0.5x の段組み） | 出力尺が理論値と一致（ffprobe）・音程/同期の実聴確認 1 点 |
 | 2 | クロマキー背景置換 | `source.chroma_key`: {color, similarity, blend, background(色 or 画像/動画パス)} | `chromakey`/`colorkey` + 背景入力の `overlay` | 緑背景フィクスチャで背景が置換された出力のピクセルサンプル検証 |
-| 3 | 基本トランジション | `cuts[].transition_out`: {type: dissolve/fade-black/fade-white, duration} | `xfade`（transition 指定があるカット境界のみ xfade 経路） | 境界フレームの中間ブレンド実在をフレーム抽出で確認・指定なし境界はハードカット維持 |
+| 3 | 基本トランジション | `cuts[].transition_out`: {type: dissolve/fade-black/fade-white/**reveal-down/reveal-up**, duration} | `xfade`（transition 指定があるカット境界のみ xfade 経路）。reveal 系は ffmpeg の `revealdown` / `revealup` | 境界フレームの中間ブレンド実在をフレーム抽出で確認・指定なし境界はハードカット維持。reveal 系は色が混ざらないため、遷移中間フレームの**上半分と下半分を別々に測って**前後カットが同居することを確認する |
 | 4 | 色調フィルター（LUT） | `output.look`: {lut(プリセット参照 or パス), intensity} | `lut3d`（intensity は `blend` 併用） | LUT 有無 2 出力のフレームピクセル差分・プリセット表 `presets/luts/`（初期 2〜3 本。2026-07-29 に `catalog/luts/` から移設） |
 | 5 | 音声マスター処理 | `audio.master`: {denoise(off/std/strong), loudnorm(target LUFS・既定 -14)} | `afftdn` / `loudnorm`（2 パスでなく 1 パス許容 v0） | 出力のラウドネス実測（ffmpeg ebur128）が目標 ±1LU |
 | 6 | 画角操作（静的クロップ / ズームキーフレーム / 段階縮小） | `cuts[].framing`: `{crop?: {x,y,w,h}（0..1 の出力相対・静的）, keyframes?: [{t,scale,cx?,cy?}]（t=カット内秒・線形補間。2 点でズーム、3 点以上で段階縮小・cx/cy 省略時 0.5）}` | 出力キャンバスへフィット済みの frame を `crop` で窓抜きし `scale` で再拡大（punch-in）。静的 `crop` は `w/h/x/y` とも定数。ズームは `crop` 自身の `w/h` が実機検証で init 時一度しか評価されない制約があるため、`scale` 側を `eval=frame` で `scale(t)` 倍に広げ、`crop` は固定 `w=width:h=height` のまま `x/y` だけを `t` の関数で追わせる方式（詳細 §4-1） | 静的 crop は出力フレームの画素でクロップ位置が宣言どおりであることを実測・ズームは開始/中間/終端フレームで可視要素の実測サイズから逆算したスケールが線形補間の理論値と一致（±5%）・3 点キーフレームは 2 段階の縮小がフレーム抽出で確認できる |
@@ -31,6 +31,32 @@
    edit-lint / fixtures / test を同時追随
 2. プレビュー（preview-engine）は v0 では**近似不要・無視でよい**（出力最優先。
    「プレビューは近似・書き出しが正」の哲学を全項目に適用。プレビュー追随は別契約）
+3. **`output.look`（#4 の LUT）の適用範囲は `cuts[]` の本編映像だけ**である。
+   `layers[]`（PinP / 人物マット / B-roll）と `overlays[]` には**掛からない**。
+   同じ絵の一部として重ねる素材の色を本編に合わせたいときは、`layers[].filter`
+   （`{type:"lut", id, intensity}`。正本 = `contract-2026-08-12-region-filter-layer-v0.md` §4）
+   へ**同じ `id` / `intensity` を明示的に宣言する**。
+   実害例（2026-08-14・リール制作）: 本編にだけ `cinematic` が乗り、重ねた人物切り抜きが
+   素の色のまま合成されて、窓の継ぎ目で肌色が食い違った。「プロジェクト全体の色」だと
+   誤解しやすいため、ここに明記する。
+
+### 2-4. reveal 系トランジション（`reveal-down` / `reveal-up`。2026-08-14 追加）
+
+**前カットが丸ごとその方向へ動いて画面外へ抜け、空いた側から次カットが現れる**
+（前カットは動きながら画面端でクロップされる）。ディゾルブのように混ざらないので、
+**同じ構図が続くトークシーンでも「場面が入れ替わった」ことが読める**のが採用理由
+（オーナー指定 2026-08-14「テンプレの基本トランジションとして必要」）。
+
+- `reveal-down` = 前カットが下へ降りる（画面上部から次カットが出てくる）
+- `reveal-up` = 前カットが上へ抜ける（画面下部から次カットが出てくる）
+- 実測（64x64・10fps・duration 1s・遷移中間 t=2.5s）: `reveal-down` で上半分 RGB(0,0,253)＝次カット /
+  下半分 RGB(252,0,0)＝前カット。`reveal-up` はこの上下が入れ替わる
+- **他の xfade と同じく、遷移の重なり分だけタイムラインが縮む**（境界 1 つにつき `duration` 秒）。
+  `layers[]` / `overlays[]` / `audio.sfx[]` を**タイムライン秒で手置き**しているプロジェクトでは、
+  トランジションを足すと後続の配置が全部ずれる。字幕は (`src`, source 秒) で書くのでエンジンが
+  追随するが、手置きの要素は自分で引き直す必要がある。尺を変えたくない場合は、
+  トランジションではなくオーバーレイで表現する（前カット最終フレームを焼いて動かす）という
+  逃げ道もあるが、静止画になるうえプロジェクト固有の焼き込みが要るので既定にはしない
 
 ## 3. 残裁定
 
@@ -53,6 +79,8 @@
 - **`tpad` の `start_mode=clone` は使わない**: カット先頭（`at_sec=0`）での静止を素直に `tpad=start_mode=clone:start_duration=X` で実装すると、後続に（本機能の他パスも含め）`fps` フィルタが一つでも挟まると出力の**最終フレームが 1 枚欠落する**バグをこの ffmpeg ビルドで実機検証した（`stop_mode=clone` には同じ問題が無いことも確認済み）。代わりに、`split` で複製した全区間トリムの一方を `trim=start_frame=0:end_frame=1`（フレーム番号ベース・fps に依存しない）で 1 フレームへ切り、`stop_mode=clone` + `stop=<フレーム数-1>`（時間指定の `stop_duration` ではなく整数フレーム数）で伸ばしてから元の全区間へ concat する
 - **フリーズ中の音声は無音挿入**（direct 音の継続やループはしない）: 直前音をループさせるとループ境目でクリックノイズが乗る（PCM の非ゼロ交差での接続）のに対し、無音挿入は決定論的でグリッチが無い。narration/BGM/SFX は出力タイムライン上の絶対秒で独立に配置される既存契約（`cuts[].speed` と同じ前提）のため、freeze による尺の伸びに合わせて自動シフトはしない
 - **v0 は gap-aware タイムライン（明示 `at`/`track`）との併用不可**: gap-aware パス（`computeVideoRuns`）の出力秒→ソース秒写像は速度係数のみを前提にした線形式で、フリーズによる非線形な静止区間があると破綻する。`cuts[].freeze` が宣言された状態で gap-aware 判定（`needsGapAwareCutTimeline`）が真になる場合、render-cut は明示的に例外を投げて止まる（silent drop を許さない契約の原則どおり、機能を無言で無視しない）。デフォルトの逐次タイムラインでのみ有効
+- **v1（2026-08-18 追記）も同じ制約**: `contract-2026-08-18-v1-render-parity.md` で v1
+  （`sources[]`）の `buildMultiSourceCutCommand` にも gap-aware タイムライン（`buildGapAwareMultiSourceCutCommand`）が入った。理由は v0 と全く同じ（`computeVideoRuns` の線形写像がフリーズを表現できない）ため、`cuts[].freeze` + 明示 `at`/`track` の組み合わせは v1 でも同じ例外で止まる
 
 ### 4-3. プレビュー乖離
 

package/vendor/docs/contract-2026-07-23-analysis-person-matte.md

@@ -121,6 +121,13 @@ HEVC alpha MOV は「Apple 系ツールへの受け渡しが要るとき」の
   がそのまま適用される。`beats` / `emphasis_words` と同じ扱いである
 - マットに `--ss` 相当のオフセットを持たせない。素材の途中区間だけを切り出したマットを
   `person_matte` に載せない（載せると時刻 0 の一致が壊れる）
+  - 一方で、**カット単位に切り出したマットを `layers[].src` へ直接置く**運用（`analysis.json` を
+    経由しない、プロジェクト固有の `assets/matte/*.mov` など）は本契約の管轄外である。
+    その場合は本節の「時刻 0 一致」が成り立たないので、**切り出しの由来（元素材 / in / out /
+    speed / fps）を素材の隣に必ず残す**こと。由来が無いと消費側は素材の頭が何の時刻かを
+    推測するしかなく、十数フレーム単位でずれたまま気づけない（2026-08-14 に実害）。
+    運用上の注意は `docs/contract-2026-08-02-preview-parity.md` §2.4 と
+    `skills/edit-plan/execution.md`「レイヤー素材の時間基準」を参照
 - 消費側は表示・書き出しのたびに `cuts[]` から timeline 秒へ射影する。射影結果を永続化しない。
   同一 source 区間が複数回現れれば、1 本のマットが複数の timeline 位置へ射影される
 - マットの尺が素材の尺より短い場合、超えた範囲は**マット無し**として扱う（エラーではない）。

package/vendor/docs/contract-2026-07-25-r6-audio-tracks-and-trim.md

@@ -63,3 +63,44 @@
 - UI: 実機で (a) 配置原則どおりの表示 (b) 音声トラック追加とアイテム移動が edit.json に
   書き戻る (c) 音源バー端ドラッグで in/out 書き戻り・リロード後保持 (d) トリマーの
   表示・調整が機能 (e) 既存トラック UI・z 順の無退行
+
+## 5. §2 追記 — sfx フェード（audio-clip-fades, 2026-08-18・オーナー裁定「クリップ主義」T2）
+
+BGM をクリップ化する裁定（内部リポ `tasks/2026-08-18-bgm-clip-placement-ruling`）に伴い、
+「音楽をクリップ（audio.sfx[]）として置いても BGM ベッドと同じフェード表現ができる」を
+満たすため、`sfxItem` に optional の `fade_in` / `fade_out`（秒・0 以上）を追加のみ拡張する
+（`version` 不変・`contract-2026-07-17-data-contract-versioning.md` の原則に従う）。
+
+### schema
+
+- `sfxItem.fade_in` / `fade_out`: 秒・省略時 0（フェードなし）。`audio.bgm.fadeIn` /
+  `fadeOut`（camelCase）とは異なり **snake_case**（既存の `gain_db` と同じ命名系列）
+- フェード対象はこのクリップの実効再生窓 `[t, t + 実効尺)`。実効尺は §2 の `[in, out)` が
+  既知なら `out − in`、`in`/`out` 省略時は素材尺（消費側が実尺を解決できた場合のみ）
+- クランプ規則は `audio.bgm.fadeIn`/`fadeOut` と同型: `fade_in`/`fade_out` それぞれ独立に
+  実効尺の半分までクランプ（render-cut が実装、edit-lint は `in`/`out` が両方既知のときだけ
+  警告できる — lint は ffprobe を持たないため実尺越えの検知は消費側の責務、という §2 本文の
+  既存原則をフェードにもそのまま適用）
+
+### 消費（render-cut + preview 3 面）
+
+- render-cut: sfx の afade を volume の直後・adelay の直前に挿入する（adelay 後だと
+  `st=0` が delay 由来の無音区間を指してしまうため）。`in`/`out` 併用時は atrim/asetpts で
+  尺をリセットした後の実効尺基準で afade を計算する
+- シェルプレビュー（akari-preview）: sfx は 1 回きりの `BufferSourceNode` 再生のため、
+  bgm の毎 tick 再計算（fadeMultiplier）ではなく、schedule 時点で
+  `gain.gain.setValueAtTime`/`linearRampToValueAtTime` によるブレークポイント列を組む
+  （`sfxFadeGainSchedule`、シーク再開時は経過秒からブレークポイントを再構成）
+- Web UI（preview-server）: bgm と同じ毎 tick 再計算方式。ただしこの層は現状 sfx の
+  `in`/`out` トリム自体を未実装のため、フェードの実効尺は常にデコード済み素材全長を使う
+  （トリム実装時に合わせて見直す）
+
+### インスペクター
+
+- akari-annotations: sfx 選択時に bgm と同じ「フェード」タブ（`fadeIn`/`fadeOut` ノブ）を出す。
+  ducking は bgm 概念のため sfx には出さない
+- 正本は `packages/edit-store`（edit.json テキスト手術）だが、本追記の実装レーン
+  （task 2026-08-18-audio-clip-fades）のファイル境界が `packages/edit-store` を含まないため、
+  書き戻りは `apps/shell/extensions/akari-annotations/src/common/sfx-fade-store.ts` に
+  境界内で完結する独立実装として置いた（`updateArrayElementByIndex` 等 edit-store の
+  export 済みユーティリティは再利用）。将来 edit-store 側の担当タスクが正本へ統合してよい

package/vendor/docs/contract-2026-08-02-preview-parity.md

@@ -57,6 +57,23 @@
 ### 2.4 レイヤー（B-roll）
 - `t` 〜 `t + duration` の窓外では非表示。**初期状態も非表示**（窓に入るまで描画しない）
 - 表示中は `currentTime` を出力時刻に同期する
+- **素材内オフセット（in トリム）は無い。素材の先頭が常に `t` に対応する**。`duration` は
+  素材の先頭から何秒使うかであって、素材のどこを使うかは選べない（`cuts[].in/out` に相当する
+  ものが `layers[]` には存在しない）。素材の途中区間を重ねたいときは**素材そのものを切り出す**
+  必要がある。
+  - 切り出した素材は「何を・どこから・どの速度で切り出したか」が失われるため、
+    **由来（元素材 / in / out / speed / fps）を素材の隣に必ず残す**こと。残っていないと、
+    次に触る人（人間・AI とも）が「素材の頭が何の時刻なのか」を推測することになり、
+    十数フレーム単位でズレたまま気づけない。
+  - 実害例（2026-08-14・リール制作）: カット単位に切り出した人物マットを「先行表示分の
+    プリロールを持っているはず」と**推測**して頭をトリムしたところ、実際は切り出し済みで
+    プリロールが無く、11〜23 フレームずれた。さらに `duration` を詰めた結果、区間の末尾で
+    マットが尽きて「人物が消えて背景だけ」になった。
+  - 素材とカットの時間対応を後から実測する場合、**フレーム差分の絶対値（`blend=difference`）は
+    使わない**。色調整（`output.look` は本編にしか掛からない = §2.4 冒頭の別項）で素材と本編の
+    色が違うと、その色差が支配して指標が平坦になり誤った結論を導く。**フレーム間差分エネルギーの
+    時系列（`tblend=all_mode=difference` → `signalstats` の YAVG）を正規化して相互相関**させると、
+    色に不変で lag を特定できる。
 
 #### 2.4.1 空間クロップ（`layers[].crop`。2026-08-06 導入）
 - `crop = { x, y, w, h }`（**0..1 正規化・ソースフレーム相対・静的**）。省略時は既定
@@ -539,7 +556,7 @@ ffmpeg の `perspective` フィルタの制約（式に時刻変数を持たな
 | `layers[].perspective`（2026-08-06 実装） | ✅（§2.4.4。実ブラウザ実測済み） | ✅（§2.4.4。tsc -b + ユニット + Web 同一計算式で担保） |
 | `cuts[].fx`（2026-08-07 実装・近似あり） | 🟡（§2.4.5。5 種対応、3 種は近似バッジ付き） | ❌（未実装） |
 | `layers[].keyframes`（2026-08-09 実装） | ✅（§2.4.7。transform/crop は連続補間。perspective は blend:"normal" のみ・書き出しの段階保持とサンプル点で一致） | ✅（§2.4.7。同左） |
-| `cuts[].static-image-source`（2026-08-12 実装。正本: `contract-2026-08-12-still-image-cut-source-v0.md`） | 🟡（`<img>`/`<video>` 出し分け + preview-engine ClipSession/Timeline の image 対応を実装。framing/freeze/transform は流用。実ブラウザでの対話的スクラブ・複数区間切替の実機検証は未実施） | ❌（スコープ外・未対応） |
+| `cuts[].static-image-source`（2026-08-12 実装。正本: `contract-2026-08-12-still-image-cut-source-v0.md`） | 🟡（`<img>`/`<video>` 出し分け + preview-engine ClipSession/Timeline の image 対応を実装。framing/freeze/transform は流用。実ブラウザでの対話的スクラブ・複数区間切替の実機検証は未実施。2026-08-17: 静止画が stylesheet の display:none に隠れたまま永久に出ない実機バグ（`img.style.display=''`）を是正） | 🟡（2026-08-17 実装 — task/2026-08-17-shell-still-image-cut-preview。#preview-still + gap と同じ壁時計クロックで表示。cut transform/framing/freeze/選択ドラッグは video のスタイル鏡写しで流用。タイムラインの静止画フィルムストリップ/サムネも同時是正（probeForFilmstrip の duration 必須ガードが静止画分岐を dead code 化していた）。Electron 実機での対話検証は未実施） |
 
 - `cuts[].framing`（静的クロップ / ズームキーフレーム）・`cuts[].freeze`（フリーズ）は
   `contract-2026-07-22-render-basics.md` #6/#7 としてレンダ（render-cut）に加え、

package/vendor/docs/contract-2026-08-03-caption-display-encoding-qc-v1.md

@@ -72,6 +72,40 @@ before checksum confirmation. Parse, field, process, or 1 MiB capture failures b
 `MEASUREMENT_ERROR` shape, keep a content-addressed artifact and receipt when structurally possible,
 leave render state in `phase:error`, return exit 1, and cannot produce an integrity candidate.
 
+### 3.1 True peak AAC overshoot guard (2026-08-17, task 2026-08-17-render-cut-true-peak-guard)
+
+The `filter_report.normalized.output_tp` loudnorm reports for the PCM stage is not the artifact's
+real true peak: the AAC re-encode that follows can measurably overshoot it (a real render measured
+`filter_report` at -1.00 dBTP against a decoded artifact at +0.23 dBFS — about +1.2 dB of
+codec-introduced overshoot; `planning/notes-2026-08-17-mac-fresh-install-bug-reports.md` #05). Two
+additive mitigations apply only when `true_peak_dbtp` is **explicit** in `audio.master` — the -1.5
+dBTP default is unchanged and unmargined:
+
+- **Applied margin.** `packages/render-cut/src/plan.mjs` hands loudnorm `configured -
+  AAC_TRUE_PEAK_OVERSHOOT_MARGIN_DBTP` (1.5 dB, `packages/render-cut/src/audio-qc.mjs`) instead of
+  the raw configured value, so the *decoded* artifact — not just the PCM stage — has a better chance
+  of landing under what the caller asked for. The receipt records both under an additive
+  `audio_qc.true_peak_margin: { overshoot_margin_dbtp, applied_true_peak_dbtp }` field;
+  `audio_qc.configured.true_peak_dbtp` is unchanged and still reports the caller's original value.
+  The margin is a fixed mitigation, not a guarantee — real-render testing found synthetic
+  high-transient material where even the margined target still decodes above 0 dBFS (this is what
+  the next mitigation exists to catch).
+- **Overshoot detection.** When `decoded_measurement.normalized.input_tp` exceeds
+  `configured.true_peak_dbtp` by more than a 0.1 dB tolerance, `buildAudioQc` appends an additive
+  `audio_qc.warnings: ["TRUE_PEAK_EXCEEDED: ..."]` entry — readable from the receipt alone, no
+  human needs to eyeball the two numbers. `verdict` deliberately **stays `"INCONCLUSIVE"`**, not a
+  new value: `packages/akari-launcher/src/status-core/integrity.mjs` (mirrored at
+  `plugin/runtime/status-core/integrity.mjs`) closed-world-validates the successful-measurement
+  branch and rejects any verdict string other than `"INCONCLUSIVE"` as a structural integrity
+  problem, and `accept-command.mjs` keys its human-review warning off that exact string. A new
+  verdict value would have misreported a legitimate receipt as malformed instead of surfacing the
+  overshoot, so exceeding true peak is additive evidence on an otherwise-`INCONCLUSIVE` receipt, not
+  a verdict of its own.
+
+Both fields are additive to the existing `configured` / `filter_report` / `decoded_measurement`
+triple — nothing already reading `audio_qc` needs to change, and their absence (when
+`true_peak_dbtp` is left at its default, or when nothing exceeded) is the unchanged legacy shape.
+
 ## 4. Recipe boundary and evidence grade
 
 Recipe `caption_style_ref` is descriptive only. It is not registry-backed and never injects caption

package/vendor/docs/contract-2026-08-12-still-image-cut-source-v0.md

@@ -6,6 +6,11 @@ updated: 2026-08-12
 
 # 静止画 cut ソース契約 v0
 
+> **読み替え注記**: 表題の `-v0` は本契約文書自身のリビジョンであり、edit.json の
+> スキーマ版（`version`）とは別物。本契約が対象とするのは edit v0 の `source.path` と
+> edit v1 の `sources[].path` の両方（語彙の区別は
+> [contract-2026-07-17-data-contract-versioning.md](./contract-2026-07-17-data-contract-versioning.md) §5）。
+
 - 日付: 2026-08-12
 - 状態: **ドラフト**（v0 実装と同時に確定させる。実装で判明した齟齬は追記で解消）
 - 前提:
@@ -157,6 +162,14 @@ Electron シェル本体（`apps/shell`）のプレビュー対応は本タス
 image-layer-parity ではシェル側 webview も同時対応していたが、本タスクの司令塔裁定でシェルは
 別タスクへ切り出されている。§3 の適合状況表にシェル列は `❌`（未対応）として記録する。
 
+**追記（2026-08-17）**: 切り出されていたシェル対応を task/2026-08-17-shell-still-image-cut-preview
+で実装した。方式は Web UI（§5.2）と同型 — `#preview-still`（`<img>`）を `#preview-video` に重ね、
+静止画セグメントのクロックは gap セグメントと同じ壁時計原点を共用する。カットの
+transform / framing / 選択ドラッグは video 要素のインラインスタイルを毎フレーム鏡写しにする
+ことで既存レールをそのまま流用。タイムライン（akari-annotations）の静止画フィルムストリップも
+同タスクで是正（`probeForFilmstrip` の duration>0 必須ガードが、ffprobe が duration を報告しない
+静止画〔§2.3〕で既存の isImage 分岐を dead code 化していた）。適合状況はパリティ契約 §3 を参照。
+
 ## 6. 適合状況の更新
 
 `contract-2026-08-02-preview-parity.md` §3 の適合状況表に `cuts[].static-image-source` 行を