From 0d6d15cd5b416c1c5e537b7b6e0cc2a282699f87 Mon Sep 17 00:00:00 2001
From: Kenta Mori <morinpic0518@gmail.com>
Date: Wed, 9 Sep 2026 09:56:30 +0900
Subject: [PATCH] feat: keep decimals in --at timestamp labels, add --name for
 a stable montage file name

- format_ts: fractional seconds (e.g. --at 3.5) render as M:SS.d instead of
  being truncated to M:SS, so two pinpoint frames inside the same second stay
  distinguishable in burn-ins and montage cell labels. Integer input is unchanged.
- --name NAME: write the montage as <output>/<NAME>.jpg instead of the
  run-id suffixed default. Rejects path separators; a trailing .jpg is
  accepted. Re-runs overwrite the file, which is what pipelines want.
- README and --help updated; smoke tests for both.

Claude-Session: https://claude.ai/code/session_01XQ8xsAfAFY4JANNooHJTax
---
 README.md             |   7 +-
 docs/project-audit.md | 306 ++++++++++++++++++++++++++++++++++++++++++
 tests/smoke.sh        |  17 +++
 vshot                 |  31 ++++-
 4 files changed, 356 insertions(+), 5 deletions(-)
 create mode 100644 docs/project-audit.md

diff --git a/README.md b/README.md
index 3e36169..d11bb88 100644
--- a/README.md
+++ b/README.md
@@ -114,12 +114,16 @@ vshot video.mp4 --scene --montage
 # Stricter scene detection (fewer frames)
 vshot video.mp4 --scene 0.5 --montage
 
-# Pinpoint extraction — re-examine specific moments (seconds, decimals OK)
+# Pinpoint extraction — re-examine specific moments (seconds, decimals OK;
+# fractional times are labelled with one decimal, e.g. 0:03.5)
 vshot video.mp4 --at 3.5,12,48 --mode detail --montage
 
 # Fixed grid columns (useful for portrait videos)
 vshot video.mp4 --montage --cols 4
 
+# Stable montage file name for pipelines (re-runs overwrite it)
+vshot video.mp4 --at 3.5,12,48 --montage --name review
+
 # Machine-readable result for pipelines
 vshot video.mp4 --montage --cleanup --json | jq -r .montage
 ```
@@ -135,6 +139,7 @@ vshot video.mp4 --montage --cleanup --json | jq -r .montage
 | `--scene [N]` | Extract only scene-change frames (0.0-1.0) | 0.3 |
 | `--at LIST` | Extract at specific times in seconds (e.g. `3.5,12,48`) | — |
 | `--cols N` | Montage grid columns | auto |
+| `--name NAME` | Montage file name (no directory, `.jpg` added) — stable names for pipelines | `<video>_montage_<run-id>.jpg` |
 | `--output DIR` | Custom output directory | `<video>_vshot/` |
 | `--cleanup` | Remove frames after montage | off |
 | `--no-timestamps` | Skip timestamp overlay | — |
diff --git a/docs/project-audit.md b/docs/project-audit.md
new file mode 100644
index 0000000..b48739c
--- /dev/null
+++ b/docs/project-audit.md
@@ -0,0 +1,306 @@
+# vshot プロジェクト監査レポート
+
+- **調査日**: 2026-07-10
+- **対象**: v0.3.0(コミット `8904ca6`、main ブランチ)
+- **手法**: 全ファイル読解、shellcheck 0.11.0、および実機での挙動検証(macOS / ffmpeg / ImageMagick)。各項目に「実測確認済み」「未検証」を明記。
+
+## 総評
+
+9 ラウンドの Codex レビューを経ており、bash スクリプトとしての堅牢性は高い水準にある(`--` によるパス保護、`awk -v` による注入対策、フォント 3 段フォールバック、実行単位の RUN_ID プレフィックス等)。秘匿情報のハードコードや外部送信は存在しない。
+
+一方で、**コアの価値提案(モンタージュ 1 枚を AI が読む)に対して、モンタージュの実寸が Claude の画像縮小制限を大きく超えるケースがある**点が最大の課題。また「macOS bash 3 互換」を宣言しながら CI に macOS ランナーがない点、プラグイン内ドキュメント(SKILL.md / watch.md / CLAUDE.md)間の乖離が目立つ。
+
+---
+
+## 1. Enhancement(既存機能の改善)
+
+### E1. モンタージュ解像度が Claude vision の縮小制限を超え、text mode の目的が損なわれる
+
+- **カテゴリ**: Enhancement
+- **対象**: `vshot:654-706`(モンタージュ生成)、`skills/video-analysis/SKILL.md`(text mode + 16 frames を推奨)
+- **現状の問題点**: 実測確認済み — `--mode text --frames 16 --montage` は横動画で **4840×2192**、縦動画で 1550×2192 のモンタージュを生成する。Claude API は長辺 1568px 超の画像を縮小するため、960px 幅のセルが実効 ~310px まで潰れ、「テキストが読める」という text mode の目的が崩れる。README のトークン試算(~1,500 tokens)は縮小後の値であり、縮小自体は暗黙の前提になっているが、**縮小によるセル解像度の損失がどこにも考慮・警告されていない**。
+- **提案内容**: (1) モンタージュ長辺が 1568px を超える場合に「セル実効解像度が落ちる」旨の警告と推奨フレーム数を stderr に表示。(2) 長辺が閾値内に収まるよう複数枚に自動分割する `--pages` オプション(`--json` の `montage` を配列化)。まず (1) だけでも価値がある。
+- **優先度**: **High** — ツールの中核ユースケース(CCC Phase B QC での text mode 運用)に直接影響し、ユーザーは劣化に気づけない。
+- **想定工数**: S(警告のみ)/ M(自動ページ分割まで)
+
+### E2. `--scene` に不正な閾値を渡すと「multiple video files not supported」と誤誘導される
+
+- **カテゴリ**: Enhancement
+- **対象**: `vshot:201-207`(--scene のオプション解析)
+- **現状の問題点**: 実測確認済み — `vshot video.mp4 --scene 1.5` は閾値の正規表現(0.0〜1.0)にマッチしないため `1.5` が 2 本目の動画パスとして解釈され、`Error: multiple video files not supported` という無関係なエラーになる。`--scene -0.1` も `Unknown option: -0.1`。ユーザーは自分のミスの内容を特定できない。
+- **提案内容**: 数値らしき引数(`^[0-9.+-]`で始まる等)が続くのに範囲外の場合は「Error: --scene threshold must be 0.0-1.0, got '1.5'」と明示的にエラーにする。
+- **優先度**: **High** — 現場ユーザーが閾値調整を試行錯誤する機能(README も 0.5 等の調整を案内)であり、遭遇確率が高い。修正は数行。
+- **想定工数**: S
+
+### E3. `--cleanup` / `--cols` が `--montage` なしだと黙って無視される
+
+- **カテゴリ**: Enhancement
+- **対象**: `vshot:655`(cleanup は montage ブロック内のみ)、`vshot:659`(cols も同様)
+- **現状の問題点**: 実測確認済み — `vshot video.mp4 --cleanup --frames 2` はフレームを削除せず、警告も出ない。「cleanup = 出力を掃除」と期待したユーザーは全フレームが残ることに気づかない。
+- **提案内容**: `--montage` なしで `--cleanup` / `--cols` が指定された場合に「--cleanup has no effect without --montage」と警告する(もしくは help に明記)。
+- **優先度**: Medium — 実害はディスク残骸程度だが、無言の無視は信頼を損ねる。
+- **想定工数**: S
+
+### E4. 均等サンプリングが動画全編をデコードするため長尺動画で遅い
+
+- **カテゴリ**: Enhancement
+- **対象**: `vshot:406-414`(fps フィルタによる抽出)
+- **現状の問題点**: デフォルトの `--frames N` は `fps=N/duration` フィルタで実装されており、ffmpeg が**全フレームをデコード**する。20 フレーム欲しいだけでも 1 時間の 4K 動画を全編デコードすることになる。一方 `--at` モードは `-ss` シークで実装済み(`vshot:463-484`)。
+- **提案内容**: `--frames` モードでも各時刻を計算して `--at` と同じシークベース抽出に統一する。タイムスタンプが正確になる副次効果もある(現在は抽出後に `i * STEP` で近似)。長尺でのシーク優位は一般知識ベースで、閾値(何秒以上でシークが勝つか)は未検証 — ベンチマークを取ってから切り替え判断を推奨。
+- **優先度**: Medium — 現場の主対象(数十秒〜数分の CCC 動画)では現状でも許容範囲。長尺対応時に効く。
+- **想定工数**: M
+
+### E5. タイムスタンプ焼き込みがフレーム毎の再エンコードで、遅くかつ画質が二重劣化する
+
+- **カテゴリ**: Enhancement
+- **対象**: `vshot:586-652`(burn-in ループ)
+- **現状の問題点**: フレームごとに ffmpeg(または ImageMagick)を 1 プロセスずつ起動し、JPEG を**デコード→焼き込み→再エンコード**している。N フレームで N プロセス + JPEG 二重圧縮による画質劣化が発生する。
+- **提案内容**: 抽出パスの `-vf` に `drawtext=text='%{pts\:hms}'` を組み込み、抽出と焼き込みを 1 パス化する(未検証 — scene/fps フィルタとの併用時の PTS 表示は要動作確認)。成立すればプロセス数は 1 になり二重圧縮も消える。フォールバック(ImageMagick / ファイル名埋め込み)の既存構造はそのまま残せる。
+- **優先度**: Medium — 動作は正しいが、20〜30 フレームで体感差が出る。
+- **想定工数**: M
+
+### E6. 1 時間超の動画でタイムスタンプが「75:00」のような分表示になる
+
+- **カテゴリ**: Enhancement
+- **対象**: `vshot:110-112`(`format_ts`)、`vshot:577-578`(ファイル名サフィックス)
+- **現状の問題点**: 実測確認済み — `format_ts 4500` は `75:00` を返す。H:MM:SS 形式がなく、1 時間超では読み手(AI 含む)が誤解しうる。
+- **提案内容**: 3600 秒以上のとき `1:15:00` 形式に切り替える。ファイル名サフィックス(`t75m00s`)も同様。
+- **優先度**: Low — 現場の主対象は短尺動画。
+- **想定工数**: S
+
+### E7. scene 0 件時(exit 2)の状態が `--json` 出力から判別できない
+
+- **カテゴリ**: Enhancement
+- **対象**: `vshot:120-142`(`emit_json`)、`vshot:503-527`(exit 2 パス)
+- **現状の問題点**: `--scene` で 0 フレームのとき exit 2 で JSON も出るが、JSON 自体には `frames: 0` 以外の手掛かりがない。パイプライン側は exit code を別途拾う必要があり、`vshot ... | jq` のようにパイプすると exit code が失われる。
+- **提案内容**: JSON に `"status": "ok" | "no_scenes"`(または `"exit_code"`)フィールドを追加する。README に exit code 一覧(0/1/2)も記載する(D3 と連動)。
+- **優先度**: Low
+- **想定工数**: S
+
+### E8. リリースフローに Homebrew tap の formula 更新が含まれていない
+
+- **カテゴリ**: Enhancement
+- **対象**: `.github/workflows/release.yml`、`README.md:49-56`(Homebrew を推奨インストールとして案内)
+- **現状の問題点**: README は Homebrew を「Recommended」としているが、release ワークフローは GitHub Release 作成までで、`ClaudeCodeCafe/tap` の formula 更新は自動化されていない(tap 側の自動化有無は本リポジトリからは未検証)。リリースの度に手動更新が必要なら、brew ユーザーには古い版が配られ続ける。
+- **提案内容**: release.yml に tap リポジトリへの formula bump(`repository_dispatch` か PAT での直接コミット)を追加。tap 側に自動化が既にあるなら、その旨を CLAUDE.md に記録してこの項目をクローズ。
+- **優先度**: Medium — 配布チャネルの鮮度に直結。
+- **想定工数**: M
+
+---
+
+## 2. Refactoring(内部品質)
+
+### R1. トップレベルに約 500 行の手続きコードが直書きされている
+
+- **カテゴリ**: Refactoring
+- **対象**: `vshot:175-775`(引数解析以降のメインフロー)
+- **現状の問題点**: 関数化されているのは補助処理のみで、probe → 抽出 → リネーム → 焼き込み → モンタージュ → サマリの主要フローが全てトップレベルにあり、グローバル変数(`FRAME_FILES`, `TS_FAILURES`, `EXTRACTED` 等)を暗黙に共有している。変更時の影響範囲が読みにくい。
+- **提案内容**: 「単一ファイル」方針(CLAUDE.md)は維持したまま、`probe_video` / `extract_frames` / `assign_timestamps` / `burn_timestamps` / `create_montage` に関数分割し、末尾に `main "$@"` を置く構成にする。共有状態はグローバルのままでよい(bash 3 制約下では妥当)が、各関数の入出力をコメント 1 行で明示する。
+- **優先度**: Medium — 機能追加(E1 のページ分割等)の前にやると後続が楽になる。
+- **想定工数**: M
+
+### R2. モンタージュのフォント再検出リトライが実質デッドコード
+
+- **カテゴリ**: Refactoring
+- **対象**: `vshot:712-720`
+- **現状の問題点**: 1 回目の `run_montage` 失敗後、`DETECTED_FONT` が空なら `detect_font` を再実行してリトライするが、`detect_font` は直前(`vshot:678`)に呼ばれて空だったばかりで、同一環境で再実行しても結果は変わらない。到達しても常に同じ失敗を繰り返すだけのパスになっている(コード読解による判断、実行トレースは未検証)。
+- **提案内容**: このリトライブロックを削除し、失敗時は既存のラベルなしフォールバック(`vshot:721-728`)へ直行させる。
+- **優先度**: Medium — 動作害はないが「フォールバックが 4 段あるように見えて実は 3 段」という誤解を将来の変更者に与える。
+- **想定工数**: S
+
+### R3. モンタージュパスの計算が 2 箇所に重複している
+
+- **カテゴリ**: Refactoring
+- **対象**: `vshot:675`(`MONTAGE_FILE=`)と `vshot:769`(`MONTAGE_PATH=` の再構築)
+- **現状の問題点**: `${OUTPUT_DIR}/${BASENAME}_montage_${RUN_ID}.jpg` という命名規則が 2 箇所に書かれており、片方だけ変更すると「Feed to AI」表示と実ファイルが乖離する。
+- **提案内容**: サマリ表示では `MONTAGE_FILE` を絶対パス化して再利用する。
+- **優先度**: Low
+- **想定工数**: S
+
+### R4. scene 0 件時のメッセージブロックが 2 箇所に重複
+
+- **カテゴリ**: Refactoring
+- **対象**: `vshot:520-527` と `vshot:540-547`
+- **現状の問題点**: 「No scene changes detected…」の警告 + サイズ表示 + `emit_json` + `exit 2` がほぼ同一内容で 2 回書かれている(ffmpeg が非 0 で終わった場合と 0 で終わった場合)。
+- **提案内容**: `report_zero_scenes()` 関数に括り出す。
+- **優先度**: Low
+- **想定工数**: S
+
+### R5. ffprobe を 4 回呼んでいる(duration / width / height / rotation)
+
+- **カテゴリ**: Refactoring
+- **対象**: `vshot:297`, `332`, `337`, `356`
+- **現状の問題点**: 1 回の `ffprobe -show_entries stream=width,height:stream_side_data=rotation:format=duration` で取得できる情報を 4 プロセスに分けており、コードも 4 ブロックに膨らんでいる。
+- **提案内容**: 1 回の呼び出しにまとめてパースする(bash 3 互換の範囲で `while read` 分解)。起動コスト削減は微小だが、エラーハンドリングが 1 箇所に集約される効果が大きい。
+- **優先度**: Low
+- **想定工数**: S
+
+### R6. フレーム数カウント(find)とリネーム対象(glob)の走査基準が不一致
+
+- **カテゴリ**: Refactoring
+- **対象**: `vshot:501`(`find "$OUTPUT_DIR" -name ...` — `-maxdepth 1` なし)と `vshot:565`(トップレベルのみの glob)
+- **現状の問題点**: `EXTRACTED` は再帰的に数えるが、リネームループはトップレベルの glob のみを走査する。RUN_ID プレフィックスのおかげで実害はほぼないが(未検証)、`tests/smoke.sh` は `-maxdepth 1` を付けており基準が揃っていない。
+- **提案内容**: `find` に `-maxdepth 1` を追加して基準を統一する。
+- **優先度**: Low
+- **想定工数**: S
+
+---
+
+## 3. Feature(新機能候補)
+
+### F1. `--range START-END` — 時間範囲を指定した抽出
+
+- **カテゴリ**: Feature
+- **対象**: `vshot`(引数解析・抽出ロジック)
+- **現状の問題点**: `--at` でピンポイント再抽出はできるが、「3:00〜4:30 だけ細かく見たい」という範囲指定ができない。watch.md のステップ 7(怪しい箇所の再検査)では複数時刻を手で列挙する必要がある。
+- **提案内容**: `--range 180-270` で該当区間のみを対象に `--frames` / `--interval` / `--scene` を適用する。ffmpeg の `-ss`/`-to` を入力側に付けるだけで既存フィルタと組み合わせられる見込み(未検証)。
+- **優先度**: Medium — 既存の「概観 → 深掘り」ワークフローの自然な補完。
+- **想定工数**: M
+
+### F2. `--audio` — 音声トラックの抽出(文字起こし連携)
+
+- **カテゴリ**: Feature
+- **対象**: `vshot`(新フラグ)、`commands/watch.md`
+- **現状の問題点**: 「AI が動画を観る」は実現したが音声は完全に捨てている。ナレーションや BGM の有無は QC 観点で重要になりうる。
+- **提案内容**: `--audio` で `audio.m4a`(または 16kHz mono wav)を出力ディレクトリに書き出し、`--json` に `"audio"` フィールドを追加。文字起こし自体は外部(whisper 等)に委ね、依存を増やさない方針を維持する。
+- **優先度**: Low — 現場ニーズの確認が先。
+- **想定工数**: M
+
+### F3. 複数動画のバッチ処理
+
+- **カテゴリ**: Feature
+- **対象**: `vshot:222-228`(現在は明示的にエラー)
+- **現状の問題点**: `Error: multiple video files not supported` と実装側で意識されており、構想の痕跡がある。QC で複数テイクを比較する場合は 1 本ずつ実行が必要。
+- **提案内容**: 複数パスを受け取り動画ごとに出力ディレクトリを分けて順次処理、`--json` は 1 動画 1 行(JSON Lines)。
+- **優先度**: Low — シェルの for ループで代替可能。
+- **想定工数**: M
+
+### F4. `--format webp` — 出力フォーマット選択
+
+- **カテゴリ**: Feature
+- **対象**: `vshot`(抽出・モンタージュの拡張子/エンコーダ)
+- **現状の問題点**: JPEG 固定。WebP なら同等画質でファイルサイズを 25〜30% 程度削減できる見込み(一般知識ベース、未検証)。Claude の Read は WebP を読める。
+- **提案内容**: `--format jpg|webp|png` を追加。ffmpeg/ImageMagick 両方の WebP サポート有無をチェックしてフォールバックする。
+- **優先度**: Low — トークン数は画素数で決まるためサイズ削減の実益はディスクと転送のみ。
+- **想定工数**: S
+
+---
+
+## 4. Documentation(ドキュメント)
+
+### D1. CLAUDE.md の構造記述が実態と乖離している
+
+- **カテゴリ**: Documentation
+- **対象**: `CLAUDE.md`(Structure セクション)
+- **現状の問題点**: `skills/video-analysis.md` と記載されているが実際は `skills/video-analysis/SKILL.md`。また `tests/`、`.github/workflows/`、`docs/`、`.claude-plugin/marketplace.json` が構造図に存在しない。テストの実行方法(`bash tests/smoke.sh`)もどこにも書かれていない。
+- **提案内容**: 構造図を実態に合わせて更新し、「Testing: `bash tests/smoke.sh`(要 ffmpeg/ImageMagick)、CI は shellcheck + smoke」を追記する。
+- **優先度**: Medium — AI エージェントが最初に読むファイルであり、乖離はそのまま作業ミスに繋がる。
+- **想定工数**: S
+
+### D2. SKILL.md が旧方式(ls -t)のままで watch.md と手順が不一致
+
+- **カテゴリ**: Documentation
+- **対象**: `skills/video-analysis/SKILL.md:15-28`、`commands/watch.md:13-16`
+- **現状の問題点**: v0.3.0 で `--json` が入り watch.md は JSON からモンタージュパスを取る手順に更新されたが、SKILL.md は `ls -t ...*_montage_*.jpg | head -1` のグロブ方式のまま。またデフォルトフレーム数が watch.md は 16、SKILL.md は用途別 12〜30、CLI 本体は 20 と三者三様で、どれが意図か判別できない。
+- **提案内容**: SKILL.md を `--json` ベースに更新し、デフォルトフレーム数の方針(なぜ CLI は 20 でプラグインは 16 か)を 1 行で明文化する。E1 の解像度バジェットが入ったら、その推奨値と整合させる。
+- **優先度**: Medium — スキルは自動トリガーされるため、旧手順のまま動き続ける。
+- **想定工数**: S
+
+### D3. README に Linux 手順・テスト実行・exit code・トラブルシューティングがない
+
+- **カテゴリ**: Documentation
+- **対象**: `README.md`
+- **現状の問題点**: (1) インストールは brew のみで、CI が動いている Linux(apt)の手順がない。(2) exit code の意味(0 成功 / 1 エラー / 2 scene 0 件)が README にも `--help` にもない — パイプライン利用(`--json`)を謳うツールとしては欠落。(3) フォント未検出時の 3 段フォールバックは書かれているが、「Warning: no usable font found」が出たときの対処(fontconfig 導入等)がない。(4) 開発者向けのテスト実行方法がない。
+- **提案内容**: 「Install (Linux)」「Exit codes」「Troubleshooting」「Development」の 4 セクションを追加する。
+- **優先度**: Medium
+- **想定工数**: S
+
+### D4. スクリプト内の `(#1)`〜`(#15)` 参照コメントが文脈を失っている
+
+- **カテゴリ**: Documentation
+- **対象**: `vshot` 全体(例: `vshot:84`, `100`, `289`, `433`)
+- **現状の問題点**: `(#8, #14)` のような番号は過去の Codex レビュー指摘番号だが、その対応表はリポジトリのどこにも残っていない。番号だけでは「何の制約でこのコードなのか」が読者に伝わらず、コメントとして機能していない。
+- **提案内容**: 番号参照を制約の内容そのもの(例: `# bc は最小構成に無いことがあるため awk を使う`)に書き換える。既に内容が併記されている箇所は番号だけ削る。
+- **優先度**: Low
+- **想定工数**: S
+
+---
+
+## 5. セキュリティ(追加チェック結果)
+
+### S1. 総合評価: 良好(重大な問題なし)
+
+- **確認済み(コード読解 + 一部実測)**:
+  - 秘匿情報のハードコード: なし。外部へのデータ送信: なし。
+  - コマンド注入対策: ユーザー入力は正規表現で検証後に使用(`--scene` → ffmpeg フィルタ、`--at` → `awk -v`)。パス操作は `--` 区切りで保護。特殊文字入りファイル名(スペース・`$`・引用符)での実行は実測で正常動作を確認済み。
+  - 依存パッケージ: ffmpeg / ImageMagick はシステム管理でリポジトリに依存ロックなし(既知脆弱性はユーザー環境依存 — 本リポジトリの管轄外)。
+
+### S2. json_escape が制御文字をエスケープしない
+
+- **カテゴリ**: Enhancement(堅牢性)
+- **対象**: `vshot:115-117`
+- **現状の問題点**: `\` と `"` のみエスケープしており、改行やタブ等の制御文字を含むファイル名では不正な JSON が出力される(理論上の指摘、未検証 — 通常のファイル名では実測で valid JSON を確認済み)。
+- **提案内容**: 改行・タブは現実に発生しうるため `sed` に `\n` `\t` の変換を追加するか、awk で 0x00-0x1F を `\uXXXX` に落とす。
+- **優先度**: Low — 攻撃面ではなく堅牢性の問題(出力を読むのは自分のパイプライン)。
+- **想定工数**: S
+
+### S3. GitHub Actions がタグピン(@v4)で SHA ピンされていない
+
+- **カテゴリ**: Enhancement(サプライチェーン)
+- **対象**: `.github/workflows/ci.yml`, `release.yml`
+- **現状の問題点**: `actions/checkout@v4` はタグ参照であり、タグの差し替えに対して脆弱。release.yml は `contents: write` を持つため影響が出る場所ではある。
+- **提案内容**: SHA ピン + Dependabot(`package-ecosystem: github-actions`)で追従する。
+- **優先度**: Low — 使用アクションは公式 1 つのみでリスクは小さい。
+- **想定工数**: S
+
+---
+
+## 6. テスト(追加チェック結果)
+
+### T1. 「macOS bash 3 互換」を宣言しながら CI に macOS ランナーがない
+
+- **カテゴリ**: Enhancement(テスト基盤)
+- **対象**: `.github/workflows/ci.yml`、`CLAUDE.md`(Tech Stack: "macOS bash 3 compatible")
+- **現状の問題点**: CI は ubuntu-latest(bash 5)のみ。プロジェクトの明示的な制約である bash 3.2 互換(macOS の /bin/bash)が一度も CI で検証されていない。配列や `${var,,}` 等の bash 4 構文が紛れ込んでも検知できない。主要ユーザー環境は macOS(Homebrew 配布)である。
+- **提案内容**: `macos-latest` ジョブを追加し `bash tests/smoke.sh` を `/bin/bash`(3.2)で実行する。ジョブ追加は数行、brew での依存導入含めても小さい。
+- **優先度**: **High** — 宣言済み制約の回帰防止として費用対効果が最も高い。
+- **想定工数**: S
+
+### T2. CI の shellcheck が tests/smoke.sh を対象にしていない
+
+- **カテゴリ**: Enhancement(テスト基盤)
+- **対象**: `.github/workflows/ci.yml`(`run: shellcheck vshot`)
+- **現状の問題点**: 実測確認済み — `shellcheck tests/smoke.sh` は SC2001(style)を現に報告するが CI では検知されない。テストスクリプト自体の品質が守られていない。
+- **提案内容**: `shellcheck vshot tests/smoke.sh` に変更し、既存の SC2001 を解消(`${JSON_OUT#*\"montage\":\"}` 等のパラメータ展開へ)。
+- **優先度**: Medium
+- **想定工数**: S
+
+### T3. スモークテストの未カバー領域
+
+- **カテゴリ**: Enhancement(テスト)
+- **対象**: `tests/smoke.sh`
+- **現状の問題点**: 30 ケース超あり主要パスは良好にカバーされているが、以下が抜けている:
+  1. **特殊文字入りファイル名**(スペース・引用符・`$`)— 本体は `--` で防御済みだが回帰テストがない(手元実測では正常動作)
+  2. **縦動画・回転メタデータ**(`vshot:355-362` の rotation スワップ)— 現場の主用途が縦動画なのにテストなし
+  3. **`--json` + `--cleanup`** で `files` が空配列になること
+  4. **`--frames` > duration のキャップ**(`vshot:407-411`)と警告文言
+  5. **サブ秒動画**(`vshot:306-308` の DURATION_INT=1 補正)
+- **提案内容**: 上記 5 系統を追加。縦動画は `ffmpeg -f lavfi -i testsrc=size=180x320` で、回転メタは `-metadata:s:v rotate=90` で生成できる(回転メタの生成方法は未検証)。
+- **優先度**: Medium — 特に (1)(2) は現場ユースケース直結。
+- **想定工数**: M
+
+---
+
+## まず着手すべき Top 5
+
+優先度と工数のバランスで選定。上から順に着手を推奨。
+
+| # | 項目 | 優先度 | 工数 | 選定理由 |
+|---|------|--------|------|----------|
+| 1 | **T1: macOS CI ランナー追加** | High | S | 宣言済みの互換性制約が未検証という構造的リスクを、数行の YAML で恒久的に塞げる。全変更の安全網になるため最初にやる価値がある |
+| 2 | **E2: `--scene` 不正閾値のエラーメッセージ修正** | High | S | 現場で遭遇しやすい誤誘導エラーを数行で解消できる。即効性最大 |
+| 3 | **E1: モンタージュ解像度バジェット(まず警告のみ)** | High | S→M | コア価値(text mode の可読性)に直結する実測済みの問題。警告表示(S)を先行させ、自動ページ分割(M)は次フェーズへ |
+| 4 | **D2: SKILL.md の `--json` 化 + フレーム数方針の統一** | Medium | S | 自動トリガーされるスキルが旧手順のままなのはプラグイン利用者全員に影響する。D1(CLAUDE.md 構造修正)も同時にやると効率的 |
+| 5 | **T2: shellcheck 対象に tests/ を追加 + SC2001 解消** | Medium | S | #1 と同じ CI ファイルを触るついでに入れられる。テスト自体の品質担保 |
+
+このセットは合計でも半日〜1 日程度で完了でき、その後の E1(ページ分割)・E5(1 パス焼き込み)・R1(関数分割)といった M 級の改善に安全に進める土台が整う。
diff --git a/tests/smoke.sh b/tests/smoke.sh
index 1eedf87..3b100b6 100755
--- a/tests/smoke.sh
+++ b/tests/smoke.sh
@@ -219,6 +219,23 @@ assert_count "out-of-range time skipped" "${TMPDIR_TEST}/at_range" "vshot_*_fram
 assert "--at + montage" "$VSHOT" "$VIDEO" --at 0.5,1.5,2.5 --montage --output "${TMPDIR_TEST}/at_montage"
 assert_count "at montage exists" "${TMPDIR_TEST}/at_montage" "*_montage_*.jpg" 1
 
+echo ""
+echo "── Montage file name (--name) ──"
+NAME_DIR="${TMPDIR_TEST}/name"
+assert "--name montage" "$VSHOT" "$VIDEO" --montage --frames 3 --name review --output "$NAME_DIR"
+assert_count "named montage exists" "$NAME_DIR" "review.jpg" 1
+assert_count "no random-suffixed montage" "$NAME_DIR" "*_montage_*.jpg" 0
+assert "--name accepts .jpg suffix" "$VSHOT" "$VIDEO" --montage --frames 3 --name review.jpg --output "$NAME_DIR"
+assert_count "still one named montage after re-run" "$NAME_DIR" "review.jpg" 1
+assert_fail "--name rejects path separators" "$VSHOT" "$VIDEO" --montage --frames 3 --name ../evil --output "$NAME_DIR"
+
+echo ""
+echo "── Timestamp labels keep decimals ──"
+TS_DIR="${TMPDIR_TEST}/ts_decimal"
+assert "--at fractional extraction" "$VSHOT" "$VIDEO" --at 0.5,1 --output "$TS_DIR"
+assert_count "fractional filename suffix" "$TS_DIR" "vshot_*_t0m00.5s.jpg" 1
+assert_count "integer filename suffix" "$TS_DIR" "vshot_*_t0m01s.jpg" 1
+
 echo ""
 echo "── Montage columns (--cols) ──"
 COLS_DIR="${TMPDIR_TEST}/cols"
diff --git a/vshot b/vshot
index c2c355d..8ca5c04 100755
--- a/vshot
+++ b/vshot
@@ -19,6 +19,7 @@ INTERVAL=""
 MONTAGE=false
 OUTPUT_DIR=""
 TIMESTAMPS=true
+NAME=""
 CLEANUP=false
 SCENE=""
 AT=""
@@ -45,6 +46,8 @@ OPTIONS:
   --mode MODE       overview | text | detail (default: overview)
   --montage         Combine all frames into a single grid image
   --cols N          Number of montage grid columns (default: auto from aspect ratio)
+  --name NAME       Montage file name, without directory (default: <video>_montage_<run-id>.jpg)
+                    Stable names make pipelines simpler; re-runs overwrite the file.
   --output DIR      Output directory (default: <video>_vshot/)
   --no-timestamps   Don't burn timestamps into extracted frames
   --cleanup         Remove individual frames after creating montage
@@ -65,7 +68,8 @@ EXAMPLES:
   ${SCRIPT_NAME} video.mp4 --frames 30 --mode detail # 30 high-res frames
   ${SCRIPT_NAME} video.mp4 --scene --montage         # scene changes only
   ${SCRIPT_NAME} video.mp4 --scene 0.5 --montage     # fewer scene changes
-  ${SCRIPT_NAME} video.mp4 --at 3.5,12,48 --montage  # pinpoint extraction
+  ${SCRIPT_NAME} video.mp4 --at 3.5,12,48 --montage  # pinpoint extraction (labels keep decimals: 0:03.5)
+  ${SCRIPT_NAME} video.mp4 --montage --name review    # fixed file name: review.jpg
   ${SCRIPT_NAME} video.mp4 --montage --json          # machine-readable result
 EOF
   exit 0
@@ -106,9 +110,12 @@ is_positive_integer() {
   esac
 }
 
-# Format seconds (int or float) as M:SS for display
+# Format seconds (int or float) as M:SS for display.
+# Fractional input (e.g. --at 3.5) keeps one decimal — M:SS.d — so two
+# pinpoint frames inside the same second stay distinguishable in the montage.
 format_ts() {
-  echo "$1" | awk '{s = int($1); printf "%d:%02d", int(s / 60), s % 60}'
+  echo "$1" | awk '{s = $1 + 0; m = int(s / 60); r = s - m * 60;
+    if (r == int(r)) printf "%d:%02d", m, r; else printf "%d:%04.1f", m, r}'
 }
 
 # ── JSON result output (--json) ────────────────────────────────────────────
@@ -215,6 +222,11 @@ while [ $# -gt 0 ]; do
         echo "Error: --cols requires a value" >&2; exit 1
       fi
       COLS_OPT="$2"; shift 2 ;;
+    --name)
+      if [ $# -lt 2 ]; then
+        echo "Error: --name requires a value" >&2; exit 1
+      fi
+      NAME="$2"; shift 2 ;;
     --json) JSON=true; shift ;;
     --no-timestamps) TIMESTAMPS=false; shift ;;
     --cleanup) CLEANUP=true; shift ;;
@@ -230,6 +242,12 @@ while [ $# -gt 0 ]; do
 done
 
 # ── Input validation (#2) ─────────────────────────────────────────────────
+if [ -n "$NAME" ]; then
+  case "$NAME" in
+    */*|.|..) echo "Error: --name must be a plain file name (no path separators)" >&2; exit 1 ;;
+  esac
+  NAME="${NAME%.jpg}"
+fi
 if [ -z "$VIDEO" ]; then
   echo "Error: no video file specified" >&2
   echo "Usage: ${SCRIPT_NAME} <video> [options]" >&2
@@ -672,7 +690,12 @@ if $MONTAGE && [ "$EXTRACTED" -gt 0 ]; then
   ROWS=$(( (EXTRACTED + COLS - 1) / COLS ))
 
   TILE="${COLS}x${ROWS}"
-  MONTAGE_FILE="${OUTPUT_DIR}/${BASENAME}_montage_${RUN_ID}.jpg"
+  if [ -n "$NAME" ]; then
+    # --name: stable, caller-chosen montage file name (overwrites on re-run)
+    MONTAGE_FILE="${OUTPUT_DIR}/${NAME}.jpg"
+  else
+    MONTAGE_FILE="${OUTPUT_DIR}/${BASENAME}_montage_${RUN_ID}.jpg"
+  fi
 
   # Use shared font detection for montage
   detect_font