akari-video 0.1.0

package/vendor/skills/analyze-project/validate-and-render.md

@@ -0,0 +1,66 @@
+# 検証とレポート生成
+
+## 1. interpretation.json を検証する
+
+`interpretation.json.tmp` に書いてから検証し、PASS したものだけを `interpretation.json` へ
+原子的に置き換える。
+
+```sh
+node packages/schemas/bin/validate-interpretation.mjs <interpretation.json のパス>
+```
+
+exit code 0 かつ `OK: ...` の出力を確認する。schema 単体では表せない意味制約（`assets[].ref` と
+`inputs.analyses[].ref` の 1:1 対応、`arc[].refs[].asset`/`relations[].target` のダングリング
+参照、`section` の `end > start`、`flag` の start/end 対関係、`open_questions[].status` と
+`answer` の整合）もこの CLI が検証する。fail した場合は黙って緩めず、原因を直して再検証する。
+
+## 2. レポートを生成する
+
+```sh
+node packages/analysis-report/render-analysis-report.mjs \
+  --analysis <ref1>=<analysis1.json のパス> \
+  --analysis <ref2>=<analysis2.json のパス> \
+  --interpretation <interpretation.json のパス> \
+  --out <report.html の出力先>
+```
+
+- **`--analysis` は必ず `<ref>=<path>` の明示形で渡す**（`ref` は `collect.md` で決めた
+  `interpretation.assets[].ref` と一致させる）。bare path のみの指定も CLI は受け付けるが、
+  それは `inputs.analyses[].path` との一意な文字列照合に頼る劣化経路であり、複数素材プロジェクト
+  では取り違えのリスクが増える（2026-07-22 改訂前の位置対応づけ規約で silent data corruption が
+  実証されている）。**analyze-project は常に明示 `ref=path` 形式を使う**。
+- `interpretation.assets[]` の全 `ref` に対応する `--analysis` が過不足なく必要。renderer は
+  `inputs.analyses[].ref` との 1:1 対応・path のクロスチェックをハードエラーで検証し、
+  通らない場合は何も書き出さない。
+- 生成前に `interpretation.json` は 1. で PASS 済みであること。renderer 自身も内部で
+  `validate-interpretation.mjs` を呼ぶため、二重に検証されるが省略しない。
+
+## 3. 開く
+
+生成した HTML はテンプレ + データ分離・自己完結（外部 CSS/font/script/remote image 参照なし）
+なので、そのままブラウザで開ける。
+
+```sh
+open <report.html の出力先>
+```
+
+`open` が使えない環境ではファイルパスを人間に提示し、ブラウザで開いてもらう。
+
+## 4. レポートの読み方（確認観点）
+
+- 全カード/行に 事実 / 解釈 のラベルが付いている（テーゼ 2 の可視化）。解釈側は
+  `relations[].evidence`/`flags[].evidence` を「根拠を見る」で開示できる。
+- 節構成は事実 + 素材の読み + 客観的関係 + 取材台帳 + 来歴に限定される。**構成案（arc）は
+  表示されない**（interpretation.json のデータとしては存在する。[interpretation.md](interpretation.md#arc-は内部データレポート非表示) 参照）。
+- 決定 UI（選択肢・ツマミ・確定ボタン）が無いことを確認する。あればテンプレ側の regression。
+- `open_questions` が 0 件の場合は「取材事項なし」の空状態文言が出る（「まだ分析していない」
+  という誤解を招く空白表示にならないことを確認する）。
+
+## よくある間違い
+
+- `--analysis` を bare path のまま複数渡し、renderer の一意照合に頼る（明示 `ref=path` を使う）。
+- validate 前の `.tmp` を確定版として扱う。
+- renderer が拒否したのに手で HTML を編集して辻褄を合わせる。
+- `arc` が表示されないことを理由に `interpretation.json` へ `arc` を書かずに済ませる
+  （schema は `arc` を必須にしている。表示されないのは意図的な仕様であり、データとしての省略は
+  許されない）。

package/vendor/skills/bake-3d/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: bake-3d
+description: 3D シーンを映像素材（クリップ）として使いたいとき、3D ベイクレシピ（scene.py）を新規作成・調整・再ベイクするときに発動する。Blender ヘッドレスでレシピを mp4 に焼き、検証し、素材ライブラリ / プロジェクトへ配置するまでを担う。映像の上に重なるオーバーレイ 3D は対象外（overlay-authoring/3d.md へ）。
+---
+
+# FORBIDDEN 級ハードルール
+
+> **Language**: Respond in the user's language — 対話・質問・承認確認・レポートはユーザーの使用言語に合わせる（例: 英語で話しかけられたら英語で応答する）。
+
+1. **ベイクを実行せずに「焼けた」と報告しない。** 出力 mp4 を ffprobe で確認し、フレームを抽出して目視するまで完了扱いにしない。
+2. **scene.py に宣言済み param 以外の外部入力を持ち込まない。** 環境変数・wall-clock・暗黙 seed の乱数・ネットワーク取得は禁止。同じレシピ + 同じ params + 同じ Blender バージョン → 同じ映像、を崩さない。
+3. **連番静止画を残さない。** mp4 へ直書きする。中間連番が必要だった場合は合成後に必ず削除する。
+4. **モデル・HDRI 等のアセット実体を改変しない。** 調整はツマミ（param）の範囲で行う。ライセンス不明のアセットをレシピに同梱しない（[harvest-asset](../harvest-asset/SKILL.md) の規律を継承）。
+5. **Blender をユーザー確認なしにインストールしない**（[setup-library/tools-check.md](../setup-library/tools-check.md) と同じ）。
+6. **`node packages/schemas/bin/validate-asset.mjs` を通さずにライブラリ入庫を「検証済み」と報告しない。**
+
+# 契約
+
+正典: [`docs/contract-2026-07-14-3d-bake-recipe.md`](../../docs/contract-2026-07-14-3d-bake-recipe.md)。
+レシピ = SSOT（scene.py + param + アセット参照）、ベイク出力 = 再生成可能キャッシュ。
+焼いた mp4 は edit.json の通常クリップとして扱う（エンジン・ビューワーは無改修）。
+
+# 1. Blender の探索
+
+```sh
+BLENDER="${AKARI_BLENDER_BIN:-}"
+[ -z "$BLENDER" ] && BLENDER="$(command -v blender || true)"
+[ -z "$BLENDER" ] && BLENDER="/Applications/Blender.app/Contents/MacOS/Blender"
+test -x "$BLENDER" && "$BLENDER" --version | head -1
+```
+
+なければ `brew install --cask blender` を提示して止まる（無断実行しない）。
+
+# 2. scene.py の authoring 契約
+
+参照実装: [`assets/3d/vintage-camera-turntable/scene.py`](../../assets/3d/vintage-camera-turntable/scene.py)
+
+- **自己完結**: レシピディレクトリ単体をプロジェクトへコピーしても動くこと。リポ内の他ファイルを import しない。アセットは `os.path.dirname(os.path.abspath(__file__))` 相対で読む
+- **引数契約**（`--` 以降を argparse で受ける）:
+  `--out <path>.mp4` / `--profile draft|final` / `--fps N` / `--frame-start N` / `--frame-end N` / `--set key=value`（複数可）
+- **PARAM_DEFAULTS 辞書 = meta.json の knobs と 1:1**。未宣言キーの `--set` はエラーにする
+- **時間はフレーム番号の純関数**。アニメーションはドライバの安全式サブセット（`frame` 変数 + 算術）または線形キーフレームで表現し、wall-clock を使わない
+- **profile は品質 2 段**: draft = EEVEE 低解像度（ツマミ調整の反復用）/ final = 出力解像度。同じ scene.py が両方を通る
+- **Blender 5.x API 注意**（5.1.2 実測）: エンジン ID は `BLENDER_EEVEE`（`_NEXT` は廃止）。動画出力は `image_settings.media_type = "VIDEO"` を先に立ててから `file_format = "FFMPEG"`（4.x に media_type は無いので hasattr で分岐）
+- 出力名へ Blender がフレーム範囲を付けるケースに備え、レンダー後に `--out` の名前へ正規化する（参照実装の `render()` を踏襲）
+
+# 3. ベイク実行
+
+```sh
+"$BLENDER" -b -P scene.py -- \
+  --out bakes/<id>-draft.mp4 --profile draft \
+  --fps 30 --frame-start 1 --frame-end 120 \
+  --set orbit_start_deg=205
+```
+
+- 実測目安（M シリーズ Mac / EEVEE / 720p / 16 samples）: 約 0.5〜0.6 秒/フレーム。draft 4 秒素材 ≒ 1 分
+- ベイク出力は `bakes/`（git ignore 済み: `*.mp4`）。消してよい。final はプロジェクト書き出し直前だけ
+
+# 4. 検証（必須）
+
+1. `ffprobe` で解像度・fps・フレーム数が指定と一致することを確認する
+2. 先頭・中間・末尾のフレームを `ffmpeg -ss <t> -frames:v 1` で抽出して目視する（構図・ライティング・アニメーションの向き）
+3. ライブラリ入庫時は中間フレームから `preview.png` を作り、`node packages/schemas/bin/validate-asset.mjs assets/3d/<id>` を通す
+
+# 5. ライブラリ入庫 / プロジェクト採用
+
+- 入庫基準は素材ライブラリ契約と同じ: シーン構築・ライティング・カメラワークの設計コストが高いレシピだけを入れる
+- meta.json は knobs を `param` で宣言し、`requires: ["blender"]`。provenance にアセットの取得元・ライセンス・梱包手順を書く
+- プロジェクト採用 = レシピ一式を `<project>/assets/3d/<id>/` へ複製 → params 上書き → ベイク → mp4 を edit.json にクリップ配置。provenance にレシピ id / 版 / params / Blender バージョンを記録する
+
+# よくある間違い
+
+- EEVEE ヘッドレスの動作を検証せず「焼ける」と報告する（GPU 環境依存。必ず実行する）
+- `THREE.Clock` 的発想で wall-clock や `random()` に依存したアニメーションを書く
+- ツマミを cssVar で宣言する（ベイクレシピは param。cssVar はオーバーレイ素材用）
+- fragment.html と scene.py を同じ素材ディレクトリに同居させる（validate-asset.mjs が拒否する）
+- .blend にテクスチャをパックして肥大化させる / 連番 EXR を残してディスクを焼く
+- draft で確認せずいきなり final を焼いて反復時間を溶かす

package/vendor/skills/compile-review-session/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: compile-review-session
+description: 録音 review セッションの audio.wav・events.jsonl・edit.snapshot.json・session.json を、analyze-footage と同じ 3 層 STT で文字起こしし、発話区切り・軌跡からの参照解決・命令形への正規化を経て review.json の open annotation とコンパイルレポートへ着地する。喋りながら行った QA セッションをチケット化するとき、recorded / transcribed セッションをコンパイルするとき、または compiled セッションを明示的に再コンパイルするときに使う。
+---
+
+# review セッションをコンパイルする
+
+> **Language**: Respond in the user's language — 対話・質問・承認確認・レポートはユーザーの使用言語に合わせる（例: 英語で話しかけられたら英語で応答する）。
+
+## ハードルール
+
+1. `audio.wav`、`events.jsonl`、`strokes.json`、`edit.snapshot.json` を変更しない。
+2. snapshot がなければ拒否する。現在の edit.json や recT から sourceT を推測しない。
+3. STT は `analyze-footage` の 3 層に相乗りし、独自 provider 設定を作らない。word 時刻のない
+   結果を採用せず、クラウドへは決定カードと明示承認なしに送信しない。
+4. 曖昧な発話を黙って捨てたり参照先を断定したりしない。`[要確認]` + low confidence へ倒す。
+5. review.json は既存 annotation のバイト列を変えず原子的に追記する。上書き・削除・ID 再利用を
+   しない。
+6. compiled セッションは既定でスキップする。`--force` でも古い annotation と
+   compiledAnnotations を保持して新 ID を足す。
+7. 1 セッションの破損で全体を止めない。manifest 破損は skip、snapshot 欠落は reject として
+   レポートし、他を続ける。
+
+## 実行順
+
+1. [compilation-rules.md](compilation-rules.md) を読み、時計、STT、発話区切り、参照解決、着地、
+   劣化の規則を確認する。
+2. プロジェクトの `review/sessions/` と `review.json` を読み、対象と既存最大 annotation ID を
+   確認する。
+3. 実案件では判断用の提案を先に作る。
+
+   ```sh
+   node skills/compile-review-session/bin/compile-review-session.mjs <project-root> \
+     --session <s-XXXX> --prepare-only --json
+   ```
+
+4. `compile-proposals.json` の原文、recRange、参照候補、暫定採否・正規化を音声・events・snapshot
+   と照合する。各 `decision` に `action: "annotate" | "discard"`、`reason`、annotation の
+   命令形 `text`、`confidence: "high" | "low"` を記入する。参照を変える必要があれば根拠を
+   確認して `reference` を修正する。曖昧なら discard せず low にする。
+5. 判断済み提案を着地する。
+
+   ```sh
+   node skills/compile-review-session/bin/compile-review-session.mjs <project-root> \
+     --session <s-XXXX> --apply-proposals --json
+   ```
+
+   compiled の再コンパイルを prepare/apply する場合は両方のコマンドへ `--force` を付ける。
+
+6. 自動一括が明示された場合だけ提案の暫定判定を直接適用する。
+
+   ```sh
+   node skills/compile-review-session/bin/compile-review-session.mjs <project-root> --json
+   ```
+
+7. CLI 結果と各 `compile-report.md` を読み、発話 N、着地 M、要確認 K、破棄内容と理由、backend、
+   warning を報告する。review.json の既存行、session 原本 4 点、スキップ対象が不変であることを
+   確認する。
+
+## オプション
+
+- `--session s-XXXX`: 1 セッションだけを処理する。
+- `--force`: compiled も再コンパイルし、新規 ID を追加する。
+- `--allow-cloud-stt`: doctor ok のクラウド候補を decision card まで評価する。送信にはさらに
+  `--cloud-provider scribe|groq --cloud-approved` が必要。
+- `--json`: 機械可読な集計を stdout に出す。
+
+## 出力
+
+- `review/sessions/s-XXXX/transcript.json`: backend provenance と word 時刻付き segments。
+- `review/sessions/s-XXXX/compile-proposals.json`: prepare 時の判断面。
+- `review/sessions/s-XXXX/compile-report.md`: 発話→着地、要確認、破棄、劣化、役割分担。
+- `review.json`: v0 annotation への追記。
+- `review/sessions/s-XXXX/session.json`: status と compiledAnnotations の追記的更新。
+
+既知の同期差として、`packages/schemas/review.schema.json` の `input` enum と現行
+`apps/shell` reader はまだ `"session"` を許可していない。enum / UI reader の拡張は別タスク
+（本スキルの境界外）であり、本スキルは accepted 契約どおり `input: "session"` を書く。