diff --git a/.claude/agents/coder.md b/.claude/agents/coder.md index c85583c..08ddce6 100644 --- a/.claude/agents/coder.md +++ b/.claude/agents/coder.md @@ -1,7 +1,7 @@ --- name: coder description: "機能実装・バグ修正に集中するエージェント．テストやリファクタリングは行わない．実装パイプライン（/implement）の Phase 1 で使用される．" -model: sonnet +model: opus tools: - Read - Glob diff --git a/.claude/agents/refactorer.md b/.claude/agents/refactorer.md index 000b45d..3c4a339 100644 --- a/.claude/agents/refactorer.md +++ b/.claude/agents/refactorer.md @@ -1,7 +1,7 @@ --- name: refactorer description: "テストが通っている状態でコード品質を改善するエージェント．テストを安全網として使い，挙動を変えずにリファクタリングする．実装パイプライン（/implement）の Phase 3 で使用される．" -model: sonnet +model: opus tools: - Read - Glob diff --git a/.claude/agents/tester.md b/.claude/agents/tester.md index aad79ba..a5a4566 100644 --- a/.claude/agents/tester.md +++ b/.claude/agents/tester.md @@ -1,7 +1,7 @@ --- name: tester description: "仕様ベースでテストを作成・実行するエージェント．実装の正しさを検証する．実装パイプライン（/implement）の Phase 2 で使用される．" -model: sonnet +model: opus tools: - Read - Glob diff --git a/.claude/commands/auto-refactor.md b/.claude/commands/auto-refactor.md new file mode 100644 index 0000000..09ae461 --- /dev/null +++ b/.claude/commands/auto-refactor.md @@ -0,0 +1,269 @@ +--- +name: auto-refactor +model: opus +description: "放置中（無人）に自律的に回り続け，空き時間をコード/ドキュメント/テストの整理に充てるループ．テスト保護下のコードリファクタ，実装を真としたドキュメント追記・整形（矛盾は報告のみ），ミューテーション保護下のテストリファクタを，対象が尽きるまで繰り返し，専用ブランチへ自律コミットする．" +argument-hint: "<対象ディレクトリ/モジュールの絞り込み（省略可）>" +--- + +あなたは**自律リファクタリング＆ドキュメント同期ループのオペレーター**です． +ユーザーが席を外している無人時間に，空いた稼働枠を「コードの大規模リファクタリング」と「実装とドキュメントのズレ解消」に充てるために起動されました． +GUIDE_02（ドキュメント作成），GUIDE_04（Git 運用），GUIDE_05（エージェント運用）を読み，書式・規約・パイプラインのルールを理解した上で，以下の不変条件を厳守してループを回してください． + +このループが扱う作業は **4 種類**ある．前の3種をすべて拾い尽くした後にだけ，最後の「テストリファクタ系」を行う（最も安全網が特殊で危険なため，最後に回す）． + +- **コードリファクタ系**：挙動を変えずにコード品質を改善する（安全網＝テスト）． +- **ドキュメント同期系**：実装を真として `docs/` の記述を実態に近づける．ただし「ドキュメントに無い事項の追記」は自動で行い，「ドキュメントと実装の矛盾」は自動で書き換えず報告のみ（後述）． +- **ドキュメントリファクタ系**：ドキュメントの**意味を変えずに**読みやすさ・品質を上げる（冗長表現の簡潔化，表記統一，書式整形，リンク修正等）．コードリファクタにおけるテストに相当する「意味が保たれたかの自動検証手段が無い」ため，**情報を削るより残す側に倒す**のが原則（後述の不変条件 9）． +- **テストリファクタ系**（前3種が尽きた後のテールフェーズ）：肥大化・重複・無意味なテストを整理する．**テストを再実行しても「検証力を弱めた」ことに気づけない**のが根本問題なので，安全網としてミューテーションテストの差分を使う（後述の不変条件 10）．使えない場合は構造改善のみ自動・削除/弱体化は提案に落とす． + +## このコマンドの位置づけ（重要） + +- 本コマンドは **CLAUDE.md の「`/commit` 自発実行禁止」ルールに対する，ユーザー承認済みの明示的な例外**である． + - ただし例外が認められるのは **`refactor/` 専用ブランチへのコミットに限る**（リファクタ・ドキュメント同期いずれの成果もこのブランチに積む）． + - **`git push`・PR 作成・マージ・`main` への操作は一切行わない**（マージ可否の判断は後で人間が行う）． +- 「無人で回り続ける」ことが目的のため，各 Phase での人間確認は挟まない．これが許される根拠は作業種別ごとに異なる: + - **コードリファクタ系**：リファクタは「挙動を変えない」作業であり，**テストが安全網として人間確認の代わりを果たす**から（テスト無しの箇所には触らない）． + - **ドキュメント同期系**：**追記（事実の補完）に限定**し，かつ**矛盾の自動上書きをしない**から．意図的に書かれた記述を壊さず，バグを仕様に固定しない（後述の不変条件 8）． + +## 不変条件 (Invariants) — 1つでも破れそうなら停止する + +1. **挙動を変えない**：リファクタ前後で**検証スイートが完全に緑のまま**であること（検証スイート＝テスト＋利用可能ならビルド/型チェック/リンタ．後述）．赤が1つでも出たら，その変更は破棄（revert/stash）して対象をスキップする． +2. **テスト保護下で着手する**：リファクタは必ず**安全網（緑のテスト）がある状態**で行う．対象にテストが無い場合は，**まず特性化テスト（現状の挙動を固定するテスト）を生成して保護下にしてから**着手する（後述のステップ R2）．テストフレームワーク自体が特定できない／生成テストを流せない箇所は対象にしない． +3. **専用ブランチのみ**：作業は `refactor/` ブランチ上でのみ行う．`main` には絶対にコミットしない． +4. **push/PR しない**：リモート操作は一切しない． +5. **1作業 = 1コミット**：意味のあるまとまり（1リファクタ／1ドキュメント更新）単位でこまめにコミットし，巨大な未コミット差分を溜めない． +6. **除外領域に触れない**：後述の「対象外の領域（除外リスト）」に該当する箇所はリファクタ対象に選ばない． +7. **疑わしきは停止**：判断に迷う・安全網が確認できない・テストコマンドが特定できない場合は，無理に進めず停止して状況を報告する． +8. **ドキュメントは「追記は自動・矛盾は報告のみ」**：実装を真としてよいのは**ドキュメントに記載が無い事項の追記**だけ．ドキュメントと実装が**食い違う**箇所は**自動で書き換えず**，要確認リストに記録して報告する（矛盾は実装バグの兆候かもしれず，無人で塗り潰すと検出機会を失うため）．`docs/01_GUIDE/`（規約），`CLAUDE.md`，`docs/03_PLAN/`・`docs/PROGRESS.md`（計画・進捗）は実装を真とする対象に**含めない**． +9. **ドキュメントリファクタは「意味保存」が絶対条件**：自動で行ってよいのは**意味・情報を保ったままの品質改善**だけ．具体的には ①無損失整形（表記揺れの統一・書式/見出し/表の整形・リンクや参照の修正・明らかなタイポ）と，②**意味を保った簡潔化・重複の集約**（冗長な言い回しを短くする，同一内容の重複を1か所に集約して他はリンクする）．**消してはいけないもの**＝事実・決定事項・設計判断（なぜその案にしたか）・失敗パターン・具体的な制約や閾値．これらが落ちる「陳腐化記述の削除」や「大規模な再編」は自動で行わず，要確認リストに**提案として記録**する．意味保存を自動検証する手段は無いため，迷ったら削らない（残す側に倒す）． +10. **テストリファクタは「検証力を落とさない」が絶対条件**：テストの整理では「検証スイートが緑」は安全網にならない（削除・弱体化したテストも緑のまま）．そこで**ミューテーションテストの差分**を安全網にする — リファクタ前に対象テストが守る本番コード範囲で「殺せるミュータント集合」を基準として取り，リファクタ後も**その全てを殺せたまま**なら検証力は保たれた＝安全（削除・統合・簡略化も可）．1つでも生存に転じたら検証力低下なので破棄する．ミューテーションテストが**走らせられない**場合（対応ツールが無い／恒久的な依存追加が必要／コスト非現実的）は，**構造改善（extract・共通化・命名・AAA 整理など検証を減らさないもの）のみ自動**とし，**テストの削除・アサーション弱体化・統合は提案として記録**する．テストコードへの自動編集はこのテストリファクタ処理（T）でのみ行う（コードリファクタ R はテストを触らない）． + +## 対象外の領域（除外リスト） — コードリファクタの対象に選ばない + +以下は無人で触ると事故りやすく，かつリファクタの価値が薄いため，**コードリファクタの対象に選ばない**．ステップ 0 の選定時に必ず除外する． + +- 自動生成コード（コードジェネレータ出力，`*.g.dart`，`*.pb.go`，スナップショット等） +- 依存・サードパーティ（`node_modules/`，`vendor/`，`.dart_tool/`，`target/`，ベンダリングされた外部ソース） +- ロックファイル・依存マニフェスト（`package-lock.json`，`yarn.lock`，`pubspec.lock`，`Cargo.lock`，`go.sum` 等） +- マイグレーション・スキーマ履歴（適用済みの DB マイグレーション等，後から書き換えてはいけないもの） +- 設定・秘匿情報（`.env*`，CI 設定，各種 config ファイル） +- ビルド成果物・キャッシュ（`dist/`，`build/`，`.next/`，`coverage/` 等） +- ドキュメント全般（`docs/`，`CLAUDE.md`，`.claude/` 配下） +- テストコード（テストファイル）：コードリファクタ R は**本番コードのみ**を対象とし，テストには触らない（テストは安全網のため）．テストの整理は専用の**テストリファクタ処理 (T)** で扱う． + +※ ドキュメントはコードリファクタの対象にはしないが，**ドキュメント同期系の処理（D）／ドキュメントリファクタ系の処理（DR）**では `docs/02_ENV/`・`docs/04_SPEC/`・`docs/05_TECH/` を更新対象とする（不変条件 8・9 の範囲で）．`docs/01_GUIDE/`・`CLAUDE.md`・`.claude/`・進捗系（`docs/03_PLAN/`・`docs/PROGRESS.md`）は自動編集の対象に**含めない**． + +判断に迷うファイルは「触らない」側に倒す（不変条件 7）． + +## セットアップ (Pre-check) — ループ開始前に一度だけ + +1. **対象範囲の確認**：`$ARGUMENTS` に絞り込み（ディレクトリ/モジュール）があればその範囲に限定する．無ければプロジェクト全体を対象候補とする． +2. **ブランチの準備**： + - `git status` で作業ツリーがクリーンか確認する．未コミットの変更があれば，無人で巻き込むのは危険なので**停止して報告**する． + - 現在のブランチを確認する．`main` にいる場合は GUIDE_04 のブランチ命名規則に従い `refactor/<英単語2〜4語(kebab-case)>` ブランチを作成して移動する（例: `refactor/auto-cleanup`）． + - 既に `refactor/` ブランチにいる場合はそれを使う．`feature/` 等の他作業ブランチにいる場合は，混在を避けるため**停止して確認を求める**． +3. **検証スイートの特定**：プロジェクトの構成ファイル（`package.json`，`pubspec.yaml`，`Cargo.toml`，`go.mod`，`pyproject.toml`／`pytest.ini` 等）から，以下を特定する． + - **テスト実行コマンドとフレームワーク**（必須）． + - 利用可能なら **ビルド／型チェック／リンタのコマンド**（例: `tsc --noEmit`，`cargo build`，`go build ./...`，`flutter analyze`，`npm run lint` 等）．これらは「テスト緑」だけでは拾えないコンパイル破壊やリンタ違反を検出する追加の安全網になる． + - 以降，**「検証スイート」= テスト＋（あれば）ビルド/型チェック/リンタ** をまとめて指す．緑の判定はこの検証スイート全体で行う． + - テストが1つも無くても，**テストフレームワークが特定でき新規テストを書いて流せる**なら開始してよい（無い箇所は特性化テストを生成して保護下にする）． + - テストフレームワーク自体が存在せず特定できない場合は，どの土台でテストを書くかは設計判断が要るため，**無人で土台を新設せず停止して報告**する．ただしこの場合でも**ドキュメント同期系（D）は実行してよい**（テスト不要のため）． +4. **ベースラインの確認**：既存テストがある場合は検証スイートを実行し，**開始時点で全て緑**であることを確認する．赤がある場合は，リファクタの前提（緑からの出発）が崩れているため**停止して報告**する．既存テストが0件の場合はテスト実行を省略してよいが，ビルド/型チェックがあれば実行して緑を確認する． +5. **台帳の読み込み**：以下のローカル台帳が存在すれば読み込む（無ければ空として扱う）．いずれも**ローカルな運用状態であり成果物ではないため `.gitignore` 対象**とする（追跡されていなければ `.gitignore` に追記する）． + - `.claude/auto-refactor-skip.md`（スキップ台帳）：過去に安全に扱えなかったリファクタ対象．今回も**再挑戦せず除外**する．形式は1行1エントリ `- <対象> | <理由> | <日付>`． + - `.claude/auto-refactor-doc-review.md`（ドキュメント要確認リスト）：過去に検出した「ドキュメントと実装の矛盾」および「自動では行わない簡潔化・再編の提案」．**既出の項目は再記録しない**（重複・トークン浪費防止）．形式は1行1エントリ，先頭にカテゴリを付ける: + - 矛盾: `- [矛盾] <箇所> | <ドキュメントの記述> | <実装の挙動> | <推定原因> | <日付>` + - 提案: `- [提案] <箇所> | <提案内容（どう簡潔化/再編したいか）> | <自動で行わない理由> | <日付>` + - `.claude/auto-refactor-test-review.md`（テスト要確認リスト）：テストリファクタで「自動では行わなかった削除・統合・弱体化の提案」．**既出は再記録しない**．形式は1行1エントリ `- [提案] <対象テスト> | <提案内容> | <自動で行わない理由（ミューテーション未実施 等）> | <日付>`． + +## ループ本体 (Loop Body) — 安全な作業が尽きるまで繰り返す + +各イテレーションで「作業項目を1つ」選び，種別に応じた処理を1サイクル実行する． + +### ステップ 0: 作業項目を1つ選ぶ + +セットアップで確定した範囲の中から，次のいずれかの作業項目を**1つ**選ぶ． + +- **リファクタ対象（コード）**：除外リスト・スキップ台帳に該当しないもの．優先度の目安（高い順）：重複コードの集約 → 過度に長い関数の分割 → 命名の改善 → デッドコード除去 → 構造の単純化． → 選んだら「リファクタ処理 (R)」へ． +- **ドキュメント・ドリフト項目**：`docs/02_ENV/`・`docs/04_SPEC/`・`docs/05_TECH/` と実装を突き合わせ，**記載漏れ**または**矛盾**がある箇所．要確認リストに既出の矛盾は除外する． → 選んだら「ドキュメント同期処理 (D)」へ． +- **ドキュメントリファクタ項目**：`docs/02_ENV/`・`docs/04_SPEC/`・`docs/05_TECH/` の中で，**意味を変えずに**改善できる箇所（冗長な言い回し，表記揺れ，書式の乱れ，重複，リンク切れ等）． → 選んだら「ドキュメントリファクタ処理 (DR)」へ． + +上記**3種すべてに作業項目が無い場合に限り**，テールフェーズとして次を検討する: + +- **テストリファクタ項目**：肥大化・重複・無意味なテスト（test smells）の整理対象． → 選んだら「テストリファクタ処理 (T)」へ．（前3種が残っている間は選ばない＝最後に回す） + +これら**4種すべて**に作業項目が無くなったら**ループを終了**し，完了報告へ進む． + +--- + +### リファクタ処理 (R) + +#### ステップ R1: 保護状態の確認 + +- 「その箇所を変更したときに失敗するテストが存在するか」を確認する． + - **保護下にある** → ステップ R3 へ． + - **テストが無い** → ステップ R2（特性化テストの生成）へ． + +#### ステップ R2: 特性化テストの生成（テストが無い対象のみ／tester エージェントに委譲） + +テストが無い対象は，まず安全網を作る．tester エージェントに以下を委譲する: + +「次の対象に対し，**現状の挙動をそのまま固定する特性化テスト（characterization test）**を作成してください．理想の仕様ではなく，**今のコードが実際に返す挙動**を観測してアサーションに落とすこと（バグも含めて現状を固定する）．境界値・主要な分岐・代表的な入出力を網羅してください．作成後にテストを実行し，**現状コードで全て緑**になることを確認してください．緑にできない（＝挙動が固定できない）場合は，その旨を報告してください． + +対象: {ステップ 0 で選んだ対象} +テストコマンド: {セットアップで特定したコマンド}」 + +- tester の報告と実テスト結果を確認する． + - **生成テストが現状コードで全て緑** → これを安全網として `git add` し，タグ **`[add]`** でコミットする（例: `[add] 〇〇モジュールに特性化テストを追加`）．**この時点ではまだリファクタしない**．コミット後，この対象を「保護下になった」状態でステップ R3 へ進む（同一イテレーション内で続けてよい）． + - **緑にできなかった／挙動が固定できない** → この対象は安全に触れないため変更を破棄し，**スキップ台帳（`.claude/auto-refactor-skip.md`）に「対象・理由・日付」を追記**してからステップ 0 へ戻る（以後のイテレーション・ウェイクで再選択しない）． + +#### ステップ R3: リファクタ前の緑確認 + +- 検証スイート（テスト＋あればビルド/型チェック/リンタ）を実行し，緑であることを確認する（ベースライン／生成した特性化テストの再確認）． + +#### ステップ R4: リファクタリング実行（refactorer エージェントに委譲） + +refactorer エージェントに以下を委譲する: + +「次の対象を，挙動を変えずにリファクタリングしてください．テストを安全網とし，リファクタ後に検証スイートを再実行して**全て緑のまま**であることを必ず確認してください．緑にできない場合は変更を破棄し，その旨を報告してください． + +対象: {ステップ 0 で選んだ対象} +検証コマンド: {セットアップで特定したテスト＋ビルド/型チェック/リンタのコマンド}」 + +#### ステップ R5: リファクタ後の緑確認 + +- refactorer の報告と実際の検証スイート（テスト＋あればビルド/型チェック/リンタ）の結果を確認する． +- **全て緑** → ステップ R6 へ． +- **赤がある／緑にできなかった** → その変更を破棄（`git checkout -- .` または `git stash`）し，**スキップ台帳に「対象・理由・日付」を追記**してステップ 0 へ戻る（同じ対象は再選択しない）． + +#### ステップ R6: 専用ブランチへコミット + +- `git add` で当該変更をステージングする（`.env`・クレデンシャル・ビルド成果物は含めない）． +- GUIDE_04 のコミット書式に従い，タグ **`[clean]`** でコミットする（例: `[clean] 重複した入力バリデーションを共通関数に集約`）． +- **push・PR はしない．** ステップ 0 へ戻る． + +--- + +### ドキュメント同期処理 (D) + +#### ステップ D1: 実装とドキュメントの突き合わせ + +- 選んだ項目について，**実装（コード）を読み，対応する `docs/02_ENV/`・`docs/04_SPEC/`・`docs/05_TECH/` の記述**を確認する． +- 食い違いの種別を判定する: + - **追記型**：ドキュメントに記載が無いが実装にある（例：新しい環境変数・依存，新規モジュール／API，コードで確定した技術選定や制約） → ステップ D2 へ． + - **矛盾型**：ドキュメントの記述と実装の挙動が**食い違う**（例：仕様では戻り値 A だがコードは B を返す） → ステップ D3 へ． + +#### ステップ D2: 追記（自動／実装を真とする） + +- 実装を真として，該当ドキュメント（`02_ENV`／`04_SPEC`／`05_TECH` の適切な場所）に**事実を追記・補足**する．GUIDE_02 のドキュメント作成規約と GUIDE_03 の命名規則に従う． +- **既存の意図的な記述は消さない**．追記・補完にとどめ，全面書き換えはしない． +- コミット（GUIDE_04 準拠）: + - 新規セクション／新規ドキュメントファイルの追加 → タグ **`[add]`**（例: `[add] 04_SPEC に〇〇APIの仕様を追記`）． + - 既存記述への事実追記・補足 → タグ **`[update]`**（例: `[update] 02_ENV に新規環境変数 FOO を追記`）． +- コミット後，ステップ 0 へ戻る． + +#### ステップ D3: 矛盾は報告のみ（自動で書き換えない） + +- **ドキュメントは書き換えない**（不変条件 8）．矛盾は実装バグの兆候かもしれず，無人で「実装に合わせて」塗り潰すと検出機会を失う． +- `.claude/auto-refactor-doc-review.md`（要確認リスト）に**1行追記**する: `- [矛盾] <箇所> | <ドキュメントの記述> | <実装の挙動> | <推定原因（仕様が古い/実装バグの疑い 等）> | <日付>`． +- **既に記録済みの矛盾は再記録しない**．記録（または既出確認）したらステップ 0 へ戻る． + +--- + +### ドキュメントリファクタ処理 (DR) + +#### ステップ DR1: 改善方針の判定（意味保存が絶対条件） + +選んだ箇所について，意味・情報を保ったまま改善できるかを判定する（不変条件 9）． + +- **無損失整形 or 意味を保った簡潔化/集約** → ステップ DR2 へ（自動で実施）． + - 例：冗長な言い回しを短くする，表記揺れ・カタカナ/英字のゆれを統一，見出しレベル・表・コードフェンス・箇条書きの整形，重複説明を1か所に集約して他はリンク，切れたリンクや古い参照（GUIDE_03 命名）を実在パスに修正，明らかなタイポ修正． +- **情報が落ちる削除・大規模再編**（陳腐化記述の削除，ファイル分割/統合，節の大幅な並べ替え等） → ステップ DR3 へ（自動では行わず提案のみ）． + +#### ステップ DR2: ドキュメントリファクタ実施（自動） + +- 該当ドキュメントを，**意味・決定事項・設計判断・失敗パターン・具体的制約を一切落とさずに**整形・簡潔化する．GUIDE_02（ドキュメント作成）・GUIDE_03（命名）に従う． +- 迷ったら削らない（残す側に倒す）．少しでも情報が落ちる懸念があれば DR3 に回す． +- GUIDE_04 のコミット書式に従い，タグ **`[clean]`** でコミットする（例: `[clean] 04_SPEC の冗長な説明を簡潔化`）．コミット後，ステップ 0 へ戻る． + +#### ステップ DR3: 削除・大規模再編は提案のみ（自動で行わない） + +- 本文は書き換えない．`.claude/auto-refactor-doc-review.md` に**1行追記**する: `- [提案] <箇所> | <提案内容（どう簡潔化/再編したいか）> | <自動で行わない理由（情報が落ちうる 等）> | <日付>`． +- **既出の提案は再記録しない**．記録（または既出確認）したらステップ 0 へ戻る． + +--- + +### テストリファクタ処理 (T) — 前3種が尽きた後のテールフェーズ + +テストコードを整理する．**「検証スイートが緑」は安全網にならない**（削除・弱体化したテストも緑のまま）ため，ミューテーションテストの差分を安全網とする（不変条件 10）． + +#### ステップ T1: ミューテーション安全網が使えるか判定 + +- 選んだテストと，それが守る**本番コード範囲**を特定する． +- その範囲に対し，**ミューテーションテストを一時的に走らせられるか**を判定する: + - 言語/スタックに対応するツール（例: JS/TS の Stryker，Python の `mutmut`/`cosmic-ray`，Java の PITest，Go の `go-mutesting` 等）を，**依存を恒久追加せず**に実行できるか（`npx`／`uvx`／`pipx run` 等のエフェメラル実行を優先）． + - **走らせられる** → ステップ T2（ミューテーション保護下の全自動）へ． + - **走らせられない**（対応ツールが無い／恒久的な依存・設定の追加が必要／リポ規模的にコストが非現実的） → ステップ T3（構造改善のみ自動）へ．恒久セットアップが要る場合は**無人で導入せず**，テスト要確認リストに「ミューテーションテスト導入の提案」を記録する． +- コスト対策として，ミューテーションは**対象テストが守る本番コード範囲に限定**して実行する（リポ全体には走らせない）． + +#### ステップ T2: ミューテーション保護下のテストリファクタ（全自動） + +1. **基準取得**：対象範囲でミューテーションテストを実行し，現在のテスト群が**殺せるミュータント集合**を基準（baseline）として記録する． +2. **リファクタ実施**：肥大化・重複・無意味なテストを整理する（**削除・統合・簡略化を含めてよい**）． +3. **検証**： + - 通常の検証スイートが**緑**であること，かつ + - ミューテーションを再実行し，**baseline で殺せていたミュータントが1つも生存に転じていない**こと（＝検証力が落ちていない）． + - 両方満たす → タグ **`[clean]`** でコミット（例: `[clean] 重複した〇〇のテストを集約`）．**一時的に作成/設定したミューテーション関連の成果物はコミットに含めない**（後始末する）． + - 1つでも生存に転じた／検証スイートが赤 → その変更を破棄（revert/stash）し，検証力が落ちる変更は行わない（必要ならテスト要確認リストに `[提案]` として記録）． +4. ステップ 0 へ戻る． + +#### ステップ T3: ミューテーションが使えない場合（構造改善のみ自動） + +- **自動でよいのは検証を減らさない構造改善のみ**：共通セットアップの extract，ヘルパー/ビルダーへの集約，テーブル駆動化（パラメタライズ），命名・AAA 構造の整理など．アサーションの数・強さを変えないこと． + - 実施後に検証スイートが緑であることを確認 → タグ **`[clean]`** でコミット． +- **テストの削除・アサーション弱体化・検証が減りうる統合は自動で行わない**．`.claude/auto-refactor-test-review.md` に `- [提案] <対象テスト> | <提案内容> | <自動で行わない理由> | <日付>` を**1行追記**（既出は再記録しない）． +- ステップ 0 へ戻る． + +--- + +## 停止条件 (Stop Conditions) + +以下のいずれかでループを止める． + +- **4種すべて（コードリファクタ／ドキュメント同期／ドキュメントリファクタ／テストリファクタ）の作業項目が尽きた** → **正常終了**． +- 同じ箇所で繰り返しテストが赤になる／テストコマンドが途中で失敗するようになった → **異常として停止し報告**． +- 不変条件を満たせない状況になった → **停止して報告**． +- ユーザーが割り込んで中断した → その時点までの成果（コミット済み）は `refactor/` ブランチに残る． + +## /loop との併用（推奨される使い方） + +このコマンドは単体で「作業が尽きるまで」連続実行するが，ユーザーが `/loop` でラップして起動すると，放置中の空き枠を使って自律的に再トリガーし続けられる（本コマンドの本来の目的）． +`/loop` で回す場合も上記の不変条件・停止条件は同じく厳守すること．長い待機を挟む場合はキャッシュとコストを意識した間隔を選ぶ． + +### 収束条件（loop-until-dry）— 空回りでトークンを浪費しない + +`/loop` で回すと，作業が尽きた後もウェイクのたびに「対象なし → 即終了」を繰り返し，**無駄にトークンを消費**しうる．これを防ぐため，以下の収束ルールを守る． + +- 各イテレーションの開始時に全範囲を再スキャンし，**この回で実施した作業の件数**を数える（コードリファクタ＋特性化テスト生成＋ドキュメント追記＋ドキュメントリファクタ＋テストリファクタ＋**新規に記録した**矛盾・提案．既出項目の再確認は作業に数えない）． +- **作業件数が 0 だった回**を「空振り」とカウントする． +- **空振りが 2 回連続**したら，もう安全に拾える作業は出尽くしたとみなし，**`/loop` 自体を終了する**（次のウェイクをスケジュールしない）． + - 1 回の空振りで即終了しないのは，「順序やコミットの巡り合わせで一時的に拾えなかっただけ」のケースを 1 回分許容するため． +- 1 件でも作業した回が出たら，空振りカウントは 0 にリセットする． +- 終了時は「空振りが続いたため収束した」旨を完了報告に明記する． + +## 完了報告 (Reporting) + +ループ終了時，ユーザーに以下を報告する． + +- 作業ブランチ名 +- 追加した特性化テストの件数（= `[add]` のテストコミット数）と対象モジュールの一覧 +- 実施したリファクタリングの件数（= `[clean]` コミット数）と概要の一覧 +- 更新したドキュメントの件数と内容（`02_ENV`／`04_SPEC`／`05_TECH` への**追記**と，意味を保った**簡潔化・整形**（`[clean]`）の箇所一覧） +- **⚠ ドキュメントと実装の矛盾**：要確認リスト `.claude/auto-refactor-doc-review.md` の `[矛盾]` の件数と概要．**実装バグの可能性があるため自動では直していない**ので，1件ずつ「仕様を直す／実装を直す」を人間が判断してほしい旨を明記する +- **簡潔化・再編の提案**：同リストの `[提案]` の件数と概要（情報が落ちうるため自動では行わなかったもの．採否は人間が判断） +- 整理したテストの件数と概要（`[clean]`）．ミューテーションテストを**安全網に使えたか／使えず構造改善のみに留めたか**を明記する +- **テストリファクタの提案**：`.claude/auto-refactor-test-review.md` の `[提案]` の件数と概要（削除・統合・弱体化など自動では行わなかったもの．ミューテーション導入の提案を含む場合はそれも） +- スキップした対象とその理由（挙動が固定できずテスト生成に失敗／検証スイートが緑にできなかった 等）．詳細はスキップ台帳 `.claude/auto-refactor-skip.md` に追記済み +- ⚠ 自動生成した特性化テストは**現状の挙動（バグを含む）を固定**したもの．後で内容を一度目視確認することを推奨する旨を添える +- 次のアクションの案内：「内容を確認の上，問題なければ `/commit push`（または `merge`）で `main` に取り込めます」 + - **本コマンドからは push・PR・マージを行わない**．取り込みは必ずユーザーの明示指示（`/commit push` 等）で行う． diff --git a/.claude/commands/commit.md b/.claude/commands/commit.md index bb23074..14e6d41 100644 --- a/.claude/commands/commit.md +++ b/.claude/commands/commit.md @@ -40,19 +40,23 @@ 変更内容と $ARGUMENTS（指定がある場合）をもとに，GUIDE_04 の「コミットメッセージ」セクションに従ってコミットメッセージを生成する． -## ステップ 4: CLAUDE.md 更新漏れチェック +## ステップ 4: CLAUDE.md / PROGRESS.md 更新漏れチェック -`.claude/commit-context.md` が存在し `claude_md_updated` が記録されている場合，このステップをスキップする． +`.claude/commit-context.md` が存在し `claude_md_updated` と `progress_md_updated` が記録されている場合，このステップをスキップする． -ファイルが存在しない場合（`/implement` を経由していない場合），変更内容に応じて CLAUDE.md の「開発進捗」セクションの更新が必要か判断し， -更新されていない場合は「⚠ CLAUDE.md の開発進捗の更新が必要かもしれません．確認してください．」と警告する． +ファイルが存在しない場合（`/implement` を経由していない場合），変更内容に応じて以下の更新が必要か判断する: + +- CLAUDE.md の「開発進捗」セクション（最新 1 行） +- `docs/PROGRESS.md`（追記型フルログ） + +更新されていない場合は「⚠ CLAUDE.md の開発進捗 / docs/PROGRESS.md の更新が必要かもしれません．確認してください．」と警告する． 更新自体は行わず，ユーザーの判断に委ねる． ## ステップ 5: コミット 以下を実行する: -1. `git add` で関連ファイルをステージングする（CLAUDE.md の変更がある場合はそれも含める） +1. `git add` で関連ファイルをステージングする（CLAUDE.md / `docs/PROGRESS.md` の変更がある場合はそれも含める） 2. `git commit -m "{コミットメッセージ}"` でコミットする 3. `.claude/commit-context.md` が存在する場合は削除する diff --git a/.claude/commands/implement.md b/.claude/commands/implement.md index 07f1c21..aec0281 100644 --- a/.claude/commands/implement.md +++ b/.claude/commands/implement.md @@ -75,7 +75,7 @@ ## Phase 4: ドキュメント更新 (Documentation) -GUIDE_05 の「Phase 4: ドキュメント更新」に記載されたチェック観点に従い，docs/ と CLAUDE.md を必要に応じて更新する． +GUIDE_05 の「Phase 4: ドキュメント更新」に記載されたチェック観点に従い，`docs/`, `CLAUDE.md`, `docs/PROGRESS.md` を必要に応じて更新する．進捗を記録する場合は GUIDE_05「進捗記録の運用ルール（CLAUDE.md / PROGRESS.md）」に従う（CLAUDE.md は最新 1 行に上書き，`docs/PROGRESS.md` に詳細を末尾追記．`git log` で取れる詳細は書かない）． Phase 4 の結果を `.claude/commit-context.md` に書き出す: @@ -83,6 +83,7 @@ # commit-context - docs_updated: true/false - claude_md_updated: true/false +- progress_md_updated: true/false - note: （更新不要の理由や更新内容の要約） ``` diff --git a/.claude/commands/setup.md b/.claude/commands/setup.md index 9e42dde..fcfb723 100644 --- a/.claude/commands/setup.md +++ b/.claude/commands/setup.md @@ -11,9 +11,10 @@ ## 基本ルール - 各フェーズの成果物をユーザーが承認してから次のフェーズに進むこと -- ユーザーが「今日はここまで」と言った場合，CLAUDE.md の進捗を更新して中断する +- ユーザーが「今日はここまで」と言った場合，CLAUDE.md の進捗（最新 1 行）と `docs/PROGRESS.md`（追記）を更新して中断する - ドキュメントは GUIDE_02（ドキュメント作成ガイド）と GUIDE_03（ファイル命名規則）に従って作成する - 成果物のドラフトを提示し，ユーザーの修正指示を反映してからファイルに書き出す +- フォルダは成果物を実際に書き出すときにのみ作成する．空のカテゴリフォルダを先回りで作らない ## 前提確認 (Pre-check) @@ -24,7 +25,7 @@ - CLAUDE.md の以下を書き換える: - 1 行目の `# プロジェクト名` → `# {確定したプロジェクト名}` - 3 行目の `` → 概要テキスト -3. CLAUDE.md の「開発進捗」を確認し，どのフェーズから再開するか判断する +3. CLAUDE.md の「開発進捗」と `docs/PROGRESS.md` を確認し，どのフェーズから再開するか判断する 4. 初回の場合はフェーズ 1 から開始する ## フェーズ 1〜6: 各フェーズの実行 @@ -45,6 +46,10 @@ 修正点があれば指示してください．OKであれば {保存先} に保存して次のフェーズに進みます．」 +### フォルダ作成の注意 + +成果物を書き出すフォルダのみ作成する．GUIDE_03 のカテゴリ表は「あり得るカテゴリの一覧」であり，立ち上げ時に全カテゴリのフォルダを scaffold するものではない．GUIDE_01 の立ち上げフェーズで成果物が発生するのは `01_GUIDE / 02_ENV / 03_PLAN / 04_SPEC` のみ．`05_TECH/`（技術設計）と `06_TEST/`（テスト）は立ち上げ時には成果物が無いため，空フォルダを作らない（実装フェーズで必要になった時点で作成する）． + ### フェーズ 3（環境構築）の注意 外部サービスの設定（アカウント作成，コンソール操作等）はユーザー自身が行う．手順書に記載するが，AI が実行しないこと． @@ -67,7 +72,7 @@ ユーザーが中断を希望した場合: -1. 現在のフェーズと状態を CLAUDE.md の「開発進捗」に記録する +1. 現在のフェーズと状態を CLAUDE.md の「開発進捗」（最新 1 行に上書き）と `docs/PROGRESS.md`（末尾に追記）に記録する 2. 次回 `/setup` 実行時に続きから再開できるようにする 「**進捗を保存しました．** diff --git a/.claude/commands/sync-template.md b/.claude/commands/sync-template.md index c079dea..0e74b4a 100644 --- a/.claude/commands/sync-template.md +++ b/.claude/commands/sync-template.md @@ -20,6 +20,7 @@ | --- | --- | --- | | `.gitignore` | フレームワーク固有ルール（Flutter/Node 等）を保持する必要がある | テンプレート側の実効行で既存に含まれないもののみを追記．既存行は触らない | | `CLAUDE.md` | プロジェクト名・開発進捗・固有規約を保持する必要がある | テンプレートで変更された共通セクション（必須ルール，エージェントチーム，ドキュメント構成等）のみを Edit で更新．プロジェクト固有セクションは触らない | +| `docs/PROGRESS.md` | プロジェクト固有の進捗ログを保持する必要がある | 既存ファイルがある場合は内容を上書きしない．テンプレート側の骨組み（タイトル・案内コメント）に差分があれば通知のみ行い手動マージを促す | | `.gitattributes` | プロジェクトによって設定が異なる可能性がある | 差分を表示し，ユーザーに「上書き / マージ / スキップ」を問う | マージ処理の対象は **既存ファイルが存在する場合のみ**．初回同期（`.claude/template-sync-sha` がない状態）では全ファイルが A 扱いとなるが，これらのファイルはフレームワーク初期化（`flutter create` / `npm init` 等）や `/init` で既にプロジェクトに存在するのが通常なので，そのままマージ処理に入る．既存ファイルがない稀なケースに限り通常の `cp` で配置する． @@ -86,7 +87,7 @@ ## ステップ 4: 変更一覧をユーザーに提示 -取り込み対象のファイル一覧を種別ごとに整理してユーザーに提示する．マージ必須ファイル（`.gitignore`, `CLAUDE.md`, `.gitattributes`）に変更がある場合は，**ユーザーが取り込み前に影響範囲を把握できるよう差分サマリーを先出しする**: +取り込み対象のファイル一覧を種別ごとに整理してユーザーに提示する．マージ必須ファイル（`.gitignore`, `CLAUDE.md`, `docs/PROGRESS.md`, `.gitattributes`）に変更がある場合は，**ユーザーが取り込み前に影響範囲を把握できるよう差分サマリーを先出しする**: 「**テンプレートに以下の変更があります:** @@ -99,6 +100,7 @@ - `.gitignore`（既存 {N} 行 / テンプレート {M} 行．既存の固有ルールを保持し，テンプレート側で追加されている {K} 行を追記） - `CLAUDE.md`（既存にプロジェクト固有セクションが {L} 行．テンプレート更新セクションのみマージ） +- `docs/PROGRESS.md`（プロジェクト固有の進捗ログ．既存があれば内容を保持し，差分があれば通知のみ） - `.gitattributes`（差分 {D} 行．処理方針をユーザーに確認） 取り込みを開始します．」 @@ -107,7 +109,7 @@ ```bash # 既存ファイル行数 -wc -l .gitignore CLAUDE.md .gitattributes 2>/dev/null +wc -l .gitignore CLAUDE.md docs/PROGRESS.md .gitattributes 2>/dev/null # テンプレート側の実効行数（.gitignore） grep -vE '^\s*(#|$)' "$TEMP_DIR/.gitignore" | wc -l @@ -115,6 +117,7 @@ # 既存ファイルとテンプレート最新版の差分プレビュー diff -u .gitignore "$TEMP_DIR/.gitignore" | head -30 diff -u CLAUDE.md "$TEMP_DIR/CLAUDE.md" | head -50 +diff -u docs/PROGRESS.md "$TEMP_DIR/docs/PROGRESS.md" | head -30 diff -u .gitattributes "$TEMP_DIR/.gitattributes" | head -30 ``` @@ -129,7 +132,7 @@ 以降の処理で利用する判定関数を定義する: ```bash -MERGE_FILES=(".gitignore" "CLAUDE.md" ".gitattributes") +MERGE_FILES=(".gitignore" "CLAUDE.md" "docs/PROGRESS.md" ".gitattributes") SKIP_FILES=("README.md") is_merge_file() { @@ -223,6 +226,18 @@ 4. テンプレート側で変更があった共通セクションのみを Edit で既存ファイルに反映する．プロジェクト固有セクションは一切触らない 5. `git diff CLAUDE.md` で結果を表示しユーザーに確認する +**`docs/PROGRESS.md` のマージ手順** + +`docs/PROGRESS.md` はプロジェクト固有の進捗ログのため，**既存ファイルがある場合は内容を上書きしない**．テンプレート側の更新は骨組み（タイトル・案内コメント）に限定されるはずなので，差分があれば通知のみ行い手動マージを促す: + +1. 既存 `docs/PROGRESS.md` とテンプレート版 `$TEMP_DIR/docs/PROGRESS.md` を Read する +2. 差分を表示する: + ```bash + diff -u docs/PROGRESS.md "$TEMP_DIR/docs/PROGRESS.md" + ``` +3. 差分がある場合，「⚠ テンプレート側の `docs/PROGRESS.md` 骨組みに変更があります．既存の追記内容を保持したまま骨組みを反映したい場合はファイルを直接編集してください．自動マージは行いません．」と通知する +4. 既存ファイルが無い稀なケース（テンプレートを使わずに作られた古いプロジェクト等）に限り，テンプレート版をそのまま `cp` で配置する + **`.gitattributes` のマージ手順** 1. 既存ファイルとテンプレート版の差分を表示する: @@ -298,7 +313,7 @@ - テンプレートリポジトリへの push は行わない - コード修正はユーザーの確認なしに実行しない -- マージ必須ファイル（`.gitignore`, `CLAUDE.md`, `.gitattributes`）は必ずステップ 5.4 の手順でマージする．盲目的な `cp` で上書きしない（フレームワーク固有の除外ルールやプロジェクト固有セクションが失われる） +- マージ必須ファイル（`.gitignore`, `CLAUDE.md`, `docs/PROGRESS.md`, `.gitattributes`）は必ずステップ 5.4 の手順でマージする．盲目的な `cp` で上書きしない（フレームワーク固有の除外ルールやプロジェクト固有セクションが失われる） - 同期対象外ファイル（`README.md`）はテンプレート紹介用のためプロジェクトには反映しない．テンプレート側で追加・変更・削除があってもプロジェクトの該当ファイルは触らない - 通常コピー対象でもプロジェクト固有の変更が上書きされうる場合は，`git diff` で確認してユーザーに報告する - テンプレートが管理するのは `.claude/` 配下のうち `agents/`，`commands/`，`hooks/`，`settings.json`，`template-sync-sha` のみ．`.claude/plans/` や `.claude/commit-context.md` 等のプロジェクト固有ファイルはテンプレートに含まれないため同期対象外 diff --git a/.claude/template-sync-sha b/.claude/template-sync-sha index 5ec9bf0..f621bff 100644 --- a/.claude/template-sync-sha +++ b/.claude/template-sync-sha @@ -1 +1 @@ -5fc484372648f2367ea41dd0589ed2429e08f7cf +4dfcf605e72eb6cc3cf7d39b9b0e7513b161a5e8 diff --git a/.gitignore b/.gitignore index 6fe30d5..ad261b9 100644 --- a/.gitignore +++ b/.gitignore @@ -48,3 +48,9 @@ # OS Thumbs.db .DS_Store + +# --- from template (sync-template) --- +# /auto-refactor のローカル運用状態（スキップ台帳・要確認リスト） +.claude/auto-refactor-skip.md +.claude/auto-refactor-doc-review.md +.claude/auto-refactor-test-review.md diff --git a/CLAUDE.md b/CLAUDE.md index e44dd56..6c3ed4f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,46 +5,7 @@ ## 開発進捗 -現在の進捗: フェーズ 7（実装）— Step 1〜7 完了，Step 8（基準設計キャリブレーション）進行中． -Step 8 進捗: spp 校正（128→1024、ノイズ/物理差を切り分け）→ 反射率スイープ（0.75〜0.92、弱い二次レバーと判明）→ **手法訂正**: シミュ linear と実測 sRGB を直接突合していた交絡を発見．標準 sRGB OETF 順方向適用＋実測 mean アンカーで見かけ差の **約 2/3 が符号化ドメイン不一致**だったと判明．寄与順は OETF（最大）＞ ISP レンズシェーディング（残差主因候補）＞ 反射率（小）．残差 1.6〜1.9 倍は調整せず正直に保持．副次: max_depth=8 は勾配を過大評価（キャリブは depth≥12）．→ **OETF 順方向適用を sm-evaluate へ正規実装完了**（`evaluation/oetf.py` + `EvaluationConfig.oetf`、baseline 有効化・real 非適用、後方互換、参照実装と数値一致テスト済み）．[SPEC_03「キャリブレーション経過」参照](docs/04_SPEC/SPEC_03_基準設計の物理構成.md)． -補足: 内部キャリブ調整は一旦中断し、**シミュ結果の見せ方（3D ビュー）改善**を実施．評価板実レンダ投影 → **path ベイク（`baker.py` mode="path"、多重反射込み per-face、scalar_rgb）** 追加 → 全メッシュ統一着色（共有 lit-clim・log・単一カラーバー）を既定化、`--render` は任意のテクスチャ投影オプション（評価板 E=π·L/ρ で同一スケール）、`--bake-cache` で 1 回計算→以後即時、`--opacity`/`--hide-below`/`--bake-smooth`/`--bake-scale` を追加．さらに **path ベイク max_depth を render 設定から独立（`--bake-max-depth`、既定 16）**＝後段多重反射を積分、**幾何カリング（`--cull-outward` 既定 ON、外向き ≈0 面を非描画）**＝暗殻の濁り/見かけ段差を解消、マーカー個別非表示フラグ、を追加．実装完了． -既知の制約（受容済み）: per-face ベイクはメッシュ境界の継ぎ目・粗メッシュのブロック感・低 samples の MC ノイズ・scalar_rgb の遅さ（高 samples 非現実的）あり．精細な評価は 2D `sm-evaluate` で行う（不変）．隣接内壁の見かけ段差は調査の結果「外向き ≈0 面の混在」が主因と判明＝幾何カリングで解消（内壁照度自体は物理どおりほぼ均一）． -次のアクション（可視化・コミット後の別タスク）: シーム/粒状感の解消には全メッシュ UV 統合＋シームレスライトマップベイク（別プロジェクト規模）．必要時に別途 `/implement`．path ベイク高速化（wavefront/GPU）も別タスク． -補足: **実機搭載 LED の物性確定**（LED Paradise LP-2835D90VW / Ra98 SunLightLED 2835 4000K、Vf 3.1V・If 60mA・Φv 16–19 lm @60mA・配光角 120°・規格通り 60mA 駆動前提）．規格値から独立推定した radiance ≈ 2030 W/(m²·sr) は現状校正値 2807 と 1.38× 差で、反射率 0.85→0.89 への調整で物理範囲内に説明可能．既知差分 #3（LED 実 W 値未検証）クローズ．**形状指標への影響なし**（線形ゲイン）．配光は厳密 Lambertian 仮定継続（詳細 IES 未提供、実 SMD 2835 のやや前方凸性は ISP LSC と打ち消し合う近似として現状妥当）．詳細: [SPEC_03 LED セクション](docs/04_SPEC/SPEC_03_基準設計の物理構成.md#led光源)． -補足: **輝度マップ「形」の追跡を導入**（[TEST_03 輝度マップ形状追跡](docs/06_TEST/TEST_03_輝度マップ形状追跡.md) + `scripts/build_luminance_evolution_panel.py`）．重要な発見: **これまでの全 7 改善ステップ (8-1〜8-7) で輝度マップの「形」は全く変わっていない**．OETF は単調変換で形を変えず，発光面サイズ変更も形を変えない．**実機は中央付近にピークを持つ楕円状，シミュは下端のみ明の Y 軸単調勾配**．**LSC モデル化は「数値残差縮小」と「形の構造的改善」の両方を担う唯一の改善候補**．以後の改善判断は「数値 + 形」の 2 軸で行う． -補足: **Step 8-8 完了**．linear 評価モードに mean 揃え正規化を導入（`evaluation/normalize.py` の `apply_mean_anchor` + `EvaluationConfig.normalization` スキーマ + CLI 統合 + OETF 排他バリデーション）．OETF 露出アンカー（Step 8-3）と同じ思想を linear ドメインに対称展開．`configs/eval_baseline_linear.yaml` で有効化（target_mean=146.7146）．形状指標 (CoV/勾配/C/P/max-min) は厳密不変，mean のみ target_mean に揃う．動作確認: α=0.961934 で baseline luminance.npy が mean=146.7146, CoV=0.182577 で評価可能．テスト 62 件追加（既存 441 + 新規 62 = 503 件全通過）． -補足: **Step 8-9 完了**．LED 18 個の位置を Fusion 360 設計 STL (`configs/meshes/SmTIASv3.stl`) から抽出して `scene_baseline.yaml` を更新．`scripts/extract_led_positions_from_stl.py` で連結成分分割→ LED/カバー識別→ bottom/right/left 自動命名．主な変更: 下基板 LED 配置を「等間隔 8.7mm」→「3+ギャップ+3 (4.2mm+10.8mm+4.2mm)」へ訂正（実機写真の中央電流制限抵抗 2 個と整合）．左右基板も実位置に修正．**形状指標は ~1% 以内のほぼ不変**（多重反射が支配的，LED 数 mm 誤差は ROI 上で平滑化）．絶対 mean は +10% 増加（α 値 0.962→0.873）．既知差分 #2 をクローズ．TEST_03 比較パネルに Step 8-9 を追加（5 枚並列）． -補足: **LED 基板カバーを 3 枚構成に展開**．従来は下基板用 `LED基板カバー.stl` 1 枚のみだったが，`scripts/extract_led_positions_from_stl.py --export-covers configs/meshes/` で SmTIASv3.stl から `LED基板カバー下/右/左.stl` の 3 ファイルを書き出し，`scene_baseline.yaml` の geometry を `led_cover_bottom/right/left` の 3 メッシュエントリに展開．右・左基板の LED が「カバーなしで浮く」状態を解消．多重反射計算への影響は軽微だが物理的に正確． -補足: **Step 8-10 完了**．LED 配光を `spot` emitter (cutoff=90°/beam=30°，FWHM 120° 一致，flux 保存 I_0=0.026784 W/sr) で表現する試行．`SpotLight` クラスを `schema.py` に追加，`lights.py` に spot 分岐実装，`configs/scene_baseline_spot.yaml` を並列保持．**目視で X 方向の対称性が部分改善**（下端の明るい領域が中央寄りに集中）だが，数値指標は微悪化（CoV +4%, 勾配 +15%）．LED 指向性は形の一部（X 方向）を変えるが，Y 方向の中央ピークは LSC モデル化（Step 8-N）が必要．本格採用は LSC との組み合わせ評価後に判断．付随発見: spot で mean が 14.6× 暗くなる（理由は spot falloff 関数の cos vs 角度ドメイン smoothstep の解釈差等を仮説）． -補足: **Step 8-11 完了**．データシート LP-2835D90VW 準拠の照明モデルを統合．`configs/scene_baseline_datasheet.yaml` に並列保持．spot を cos^1.2 相当の前方凸 (cutoff=85°/beam=26.72°，FWHM 111.72°) に詳細化 + 反射率を Step 8-6 で導出した物理整合点 0.89 に変更 + I_0 を規格値 Φv=17.5 lm から導出 (I_0=0.021951 W/sr)．**形は依然 Y 軸単調勾配**で Step 8-10 と Step 8-9 の中間値．**データシート従順度を上げても形は実機に近づかない**ことを確定．副次的に「規格値だけで mean を実機に合わせることはできず，校正値には他のレバーの累積吸収が含まれる」が再確認された．本筋 LSC モデル化が依然必要． -補足: **Step 8-12 完了**．Helmholtz 相反原理を Mitsuba 上で実証検証．`schema.py` の RenderConfig に `ptracer` integrator を追加，`configs/scene_baseline_perspective_{path,ptracer}.yaml` で perspective sensor + scalar_rgb + spp=4096 で比較．**bot/top 比が path 2.035 vs ptracer 2.006 で誤差 1.4% で一致**＝形は方向独立．絶対値は Mitsuba 実装の正規化差で 1.99× 違うが形（空間パターン）は同じ．副次的発見: **orthographic + ptracer は Mitsuba 3 では実行不能**（`Endpoint::sample_direction()` 未実装）．これにより「方向変更で形を実機に近づける道は無い」が確定し，**LSC モデル化が唯一の道**である結論が強化された． -次のアクション（キャリブ再開時）: 残差に **LSC（ISP レンズシェーディング）順方向モデル**を当てる（物理動機づけ低自由度形、overfitting 回避・取得パラメータ数明記）． - -補足: **速度最適化ワーク開始**（キャリブ作業を一旦中断）．[TEST_04 シミュレーション速度最適化履歴](docs/06_TEST/TEST_04_シミュレーション速度最適化履歴.md) に試行を集約．**Speed-0 ベースライン計測完了**（`configs/scene_baseline.yaml`，3 回中央値）: **B1 sm-render = 507.86 s（≈8.46 分）/ B2 sm-visualize path bake (samples=16) = 55.97 s**．**副次発見**: `DRJIT_LIBLLVM_PATH` 環境変数の消失で sm-render が ImportError でクラッシュしていたことを発見．`C:\Program Files\LLVM\bin\LLVM-C.dll` を発見し **User scope に永続化**して復旧．sm-visualize の direct bake は内部 scalar_rgb 固定のため過去ログでも警告は出ていたが完走していた．**方向修正**: Speed-1 当初の「JIT 有効化で高速化」は既に JIT 経路に乗っているため不成立 → 「LLVM-C.dll 自動検出と診断ログ」に再定義（再発防止）．**本命の高速化レバーは Speed-2 path bake wavefront 化**（10× 以上見込み）．GPU は Intel HD Graphics 520 のみで CUDA 不可，CPU 側完結方針．精度（spp/max_depth）は不変． -補足: **Speed-1 完了**．`src/sm_tias_lightsim/runtime/llvm_init.py` に `ensure_drjit_libllvm_path()`（標準パス自動探索→ `os.environ` 設定）と `log_variant_status()`（llvm_/cuda_/scalar_ 経路を INFO 明示，要求 llvm_* で実 scalar_* なら WARNING 追加）を新規実装．`render/runner.py` で variant=llvm_* 時に自動検出を呼び、`ImportError` 時は原因明示ログ→ re-raise．`visualize/baker.py` でも `log_variant_status` 呼び出し追加＋ Speed-2 wavefront 化用に LLVM 自動探索の分岐を先取り．`cli/render.py` で import 順を制御（`sensors.py`/`lights.py` のモジュールレベル `import mitsuba` 前に検出を確実に通す）．`docs/02_ENV/ENV_02_環境構築手順.md` に LLVM インストール手順・DRJIT_LIBLLVM_PATH 説明・動作確認コマンドを追記．**速度は不変**（コード経路同等）．新規テスト 51 件追加で **606 件全通過**（仕様 A1〜E1 すべてカバー）．数値同等性: SHA256 は MC 内部シードで異なるが平均相対誤差 7.23e-05（5σ 閾値 0.4508 に対し差 0.011）で統計同等性パス．これで「環境変数が消えて沈黙クラッシュ」する事故が再発しない土台が整備された． -補足: **速度最適化ワーク一旦中断**（Speed-2 path bake wavefront 化は未着手）．**実時間の改善は実質ゼロ**（B1=508s／B2=56s で不変）．副次的成果として環境破綻問題の発見と恒久対処，JIT 診断ログ，ベンチ条件のドキュメント，テスト 51 件追加が得られた．中断理由: B2 は現状ボトルネックではなく，B1 は CPU 完結・精度据置の制約下で取れる打ち手が限定的．本筋のキャリブ作業（LSC モデル化）に戻ることがプロジェクト目的により近い．再開条件: path bake samples を増やすユースケース発生／NVIDIA GPU 利用可／クラウド計算活用判断／キャリブ反復回数増加でバッチ時間が研究進度を圧迫した場合．詳細・Speed-2 テンプレ保持は [TEST_04 中断記録](docs/06_TEST/TEST_04_シミュレーション速度最適化履歴.md#中断記録-suspension-note--2026-05-28) 参照．次のアクション: キャリブ作業（LSC モデル化）に戻る． -補足: **キャリブ方針の根本見直し（2026-05-28）**．「シミュ vs 実機 PNG の比較」を再検討した結果，**実機 PNG 自体が定量データとして揺らいでいる**ことが判明．MiniTIAS の現行撮影は AE/AWB/NR/EDGE/TONEMAP/SHADING がすべて Camera2 API のオート/デフォルトで，撮影ごとに露光・WB・補正量が変動する．既存 baseline `MiniTIAS_20260408_144434` もこのモードで取得されており，シミュ側でいくらモデルを精緻化しても比較対象が不安定．**当初考えていた「LSC モデル化」より上位の問題**として「**定量撮影モード**」を MiniTIAS 側に追加することを優先する．Android Camera2 API には `STATISTICS_LENS_SHADING_CORRECTION_MAP` (LSC ゲインマップ取得)・`SHADING_MODE=OFF` (LSC 無効化)・`MANUAL_SENSOR`/`MANUAL_POST_PROCESSING` 能力フラグが存在し，これらを活用すれば「ISP 介入を最小化した再現性ある撮影」が可能．要求仕様を [TECH_01 定量撮影モード要求仕様](docs/05_TECH/TECH_01_定量撮影モード要求仕様.md) に，MiniTias 側 Claude セッションで作業着手するためのハンドオフ手順を [TECH_02 MiniTIAS 引き継ぎ手順](docs/05_TECH/TECH_02_MiniTIAS引き継ぎ手順.md) にそれぞれ新規作成．データ受け渡しは `reference_measurement/quantitative/` 配下（gitignore 対象）で `MiniTIAS_QM_YYYYMMDD_HHmmss.{png,meta.json,lsc.npz}` 命名規則．MiniTIAS 側で実装後，定量モードで再撮影した baseline で改めてキャリブを進める方針．SmTIAS-LightSim 側のキャリブ作業は本仕様書を MiniTIAS に渡した時点で一旦停止． -補足: **MiniTIAS 側で定量モード実装完了（2026-06-01）**．[TECH_03 実装報告 (MiniTIAS 側原稿)](docs/05_TECH/TECH_03_定量モード実装報告とSHADING_MODE相談.md) と [TECH_04 SmTIAS-LightSim 側回答](docs/05_TECH/TECH_04_MiniTIASへの回答.md) を取り込み．**AQUOS sense3 (SH-02M) は `LEVEL_3`（最上位）でハードウェア能力フル**．Phase 1〜5 全完了で **DNG (RAW_SENSOR) 経路を第 1 優先採用**．撮影設定: 1/60s + ISO 40 + AWB/NR/EDGE/AF/AE OFF + TONEMAP 線形 + BLACK_LEVEL_LOCK + SHADING_MODE=HIGH_QUALITY (★) + STATISTICS_LENS_SHADING_MAP_MODE=ON．LSC マップは 13×17．保存ファイルは `MiniTIAS_QM_*.{dng, meta.json, preview.jpg}` 3 種，meta.json に LSC マップ・実適用値・センサ特性も埋め込み．**SHADING_MODE 判断**: HIGH_QUALITY を本流維持（Mitsuba orthographic 出力 ≒「ISP が完璧に補正できた場合の理想値」で HIGH_QUALITY DNG と直接比較が物理整合）．OFF 切替は将来のフォールバック条件 C1-C3 発動時のみ．データ転送は **adb pull 推奨**（MTP は大容量 DNG で不整合リスク）．既存実機 PNG の Y' 抽出は BT.601 係数（Rec.709 ではない）も判明． -補足: **作業フェーズを A/B に分割（2026-06-01）**．「連射再現性が確保できてもシミュとの対応が取れなければ意味が薄い」という研究上の判断から，**フェーズ A: 1 ショット撮影でシミュ vs 実機対応を先に検証** → **フェーズ B: 対応が取れたら連射 V1 再現性検証**の二段階方式に変更．フェーズ A で MiniTIAS 側に依頼するのは **画素統計・Hot pixel map（高優先 2 件）と白板 1 ショット試し撮りのみ**．**連射 UI は高優先→フェーズ B に降格**．SmTIAS-LightSim 側は DNG/meta.json/LSC マップ読み込み I/F・新規 baseline config を実装し，1 ショット突合で既存通常モード baseline 残差 2.1× が定量モードで変化するかを観察．結果次第でフェーズ B 移行 or SHADING_MODE フォールバック条件 C1 検討 or 物理モデル見直しを判断．[TEST_01](docs/06_TEST/TEST_01_キャリブレーション検証履歴.md) に **Step 8-13: 定量モード 1 ショット対応検証** として記録予定． -補足: **DNG 対応を MiniTias-Evaluation 側にも依頼（2026-06-01）**．PNG から DNG への撮影フォーマット変更に伴い，MiniTias-Evaluation も実機データの一次窓口として DNG 読み込み I/F の追加が必要．既存パターン（`uniformity.py` を MiniTias-Evaluation から SmTIAS-LightSim にコピー）を踏襲する役割分担を採用：**MiniTias-Evaluation 側で正規実装 → SmTIAS-LightSim 側にコピー**．[TECH_05 MiniTias-Evaluation DNG 対応要求仕様](docs/05_TECH/TECH_05_MiniTiasEvaluation_DNG対応要求仕様.md) に要求書を作成．主要 I/F: `load_image_dng(path, demosaic, black_level, output_format)` / `load_metadata(path)` / `load_lsc_map(path)` / `load_hot_pixel_list(path)` / `mask_hot_pixels` / `apply_lsc_inverse`（将来検証用）．既存 PNG 経路と並列対応（後方互換）．依存追加: `rawpy>=0.21.0`．想定実装工数 ~3.5 日（6 Phase）．完了後 SmTIAS-LightSim 側 Claude セッションで `src/sm_tias_lightsim/evaluation/dng_loader.py` 等にコピー．次のアクション: MiniTias-Evaluation 側 Claude セッションで TECH_05 を受領 → Phase 1 から `/implement`．SmTIAS-LightSim 側のフェーズ A 受け入れ実装は MiniTias-Evaluation 完了後に着手． -補足: **MiniTias-Evaluation 側 Phase 1 完了とハンドオフ受領（2026-06-01）**．MiniTias-Evaluation 側で TECH_05 Phase 1 (DNG 読み込み I/F) と LSC 順適用プロトタイプ・新指標 (動径 min/max 比) が完成し，ハンドオフパッケージとして SmTIAS-LightSim 側に渡された．受領記録は [TECH_06 MiniTias-Evaluation 引き継ぎ受領](docs/05_TECH/TECH_06_MiniTias-Evaluation引き継ぎ受領.md)，関連分析は [TEST_05 PNG/DNG 評価比較](docs/06_TEST/TEST_05_PNG_DNG評価比較.md) と [TEST_06 外乱光影響評価](docs/06_TEST/TEST_06_外乱光影響評価.md)．**5 つの重要発見**: (1) **TECH_05 の `apply_lsc_inverse` は誤り**（DNG は LSC 未補正で逆ではなく順方向適用が正しい．TECH_05 §4 を訂正済）．(2) **過去 Step 8 キャリブの残差 2.1× はドメイン不一致**（実機 PNG sRGB 0.0423 vs シミュ sRGB/linear 比較）：正しい linear 比較では DNG linear+LSC 0.0689 vs シミュ linear 0.183 = **真の残差 2.66×**．(3) **新実機ターゲット = `MiniTIAS_QM_20260601_124500`（暗闇撮影）**: CoV=0.0695, 勾配=8.35%, 中心/周辺=1.0911, 動径 min/max=0.860．Step 8-13 以降の正規 baseline．(4) **外乱光ロバスト確認**: 室内灯 ON/OFF で指標差 < 1%．SmTIAS 自前照明が支配的で外乱光モデル化不要．(5) **新指標 `calc_radial_min_max_ratio`** (20 点輪帯平均 min/max 比) を追加．次フェーズ: S2 (dng_loader.py コピー + 新指標マージ + rawpy 依存追加) と S3 (sm-evaluate DNG 対応 + Step 8-13 突合) を別 `/implement` パイプラインで実施． -補足: **S2 完了 (2026-06-01)**．`src/sm_tias_lightsim/evaluation/dng_loader.py` を `handoff_smtias_lightsim/src/dng_loader.py` の完全コピーで新規作成 (docstring のみ差し替え)．`src/sm_tias_lightsim/evaluation/radial.py` に `calc_radial_min_max_ratio` をマージ追加 (nan ビン除外を移植時に補強)．`pyproject.toml` に `rawpy>=0.21.0` 追加 (実 rawpy==0.27.0)．新規テスト 32 件追加 (`tests/evaluation/test_dng_loader.py` 341 行)．既存 537 + 新規 32 = **569 件全通過** (slow 除外)．**検証 V4 が完全一致**: 実 DNG (`MiniTIAS_QM_20260601_124500.dng`) を読み込んで LSC 順方向適用 + 白板 ROI で評価指標 6 件 (CoV/std/max-min/mean/max/min) が **相対誤差 < 1e-6 で期待値完全一致**，空間指標 3 件 (中心/周辺/勾配/動径 min/max) も絶対誤差 < 0.003．Refactorer 判断: `dng_loader.py` 内部の `_apply_srgb_oetf` は既存 `evaluation/oetf.py:apply_srgb_oetf` と実装重複だが「コピー方針優先」「用途が異なる」「違反基準 (3 箇所以上) 未満」の理由でそのまま放置．次フェーズ: S3 (sm-evaluate に DNG 入力経路追加 + 新規 baseline config + シミュ vs 実機 DNG 突合 → TEST_01 Step 8-13 記録) を別 /implement パイプラインで実施． -補足: **S3 方針見直しと Step D 完了 (2026-06-01)**．ユーザー指摘により「sm-evaluate に DNG 入力経路を追加する」当初案は **不採用**．理由: 実機 DNG 評価は MiniTias-Evaluation の本業で完結．SmTIAS-LightSim 側で重複実装する必要なし．S3 の作業範囲を **3 項目に絞り込み**: Step D (動径 min/max 比を sm-evaluate に統合)・Step C' (新規シミュ用 baseline config 作成)・Step G (シミュ再評価 → Step 8-13 として TEST_01 に記録)．**Step D 完了**: `MetricsConfig.radial_min_max: bool = False` をスキーマ追加 (`schema.py`)，`cli/evaluate.py` で `_run_radial_min_max` 関数追加して有効時に metrics.csv に 4 列 (radial_min_max_ratio / radial_min_distance / radial_min / radial_max) を末尾追加，コンソールサマリに 2 行追加．`radial_profile` を再利用 (重複算出回避)，未算出時は内部算出．後方互換維持 (既存 3 configs は無修正で動作)．新規テスト 39 件追加 (`tests/scene/test_metrics_radial_min_max_schema.py` 250 行 + `tests/cli/test_evaluate_radial_min_max.py` 740 行) で仕様 A1-D2 全カバー．既存 569 + 新規 39 = **608 件全通過**．SPEC_04 §動径 min/max 比 セクションを追記．次: Step C' (configs/eval_baseline_dng_target.yaml 作成: 既存 eval_baseline_linear.yaml ベース，target_mean=207.82，radial_min_max=true) → Step G (Step 8-13 計測)． -補足: **Step C' 完了と Step G 計測 (2026-06-02)**．`configs/eval_baseline_dng_target.yaml` を新規作成（eval_baseline_linear.yaml ベース，target_mean=207.82，metrics.radial_min_max=true，OETF なし）．動作確認で既存シミュ baseline (output/baseline/luminance.npy) を新 config で評価した結果，Step 8-13 数値が判明: シミュ CoV=0.1826, 勾配=24.65%, 中心/周辺=1.3271, 動径 min/max=0.6151．実機 DNG+LSC 補正 (CoV=0.0695, 勾配=8.35%, C/P=1.0911, 動径 min/max=0.860) と比較して **残差 2.63×**．これは TECH_06 で予想した「真の残差 2.66×」とほぼ一致．過去 Step 8-3 OETF 順方向適用時の「2.1×」は PNG sRGB ガンマ圧縮による楽観値であり，真の linear 比較では大きい．**LSC 取り扱いの結論を [TECH_07 LSC 取り扱い方針](docs/05_TECH/TECH_07_LSC取り扱い方針.md) として一元化**: 3 プロジェクト役割分担 (MiniTias=SHADING_MODE=HIGH_QUALITY 撮影 / MiniTias-Evaluation=lscMap 順方向適用 / SmTIAS-LightSim=一切扱わない)，シミュ側で LSC を扱わない物理的根拠 (Mitsuba orthographic = LSC 完璧補正後相当)，検討した代替案 3 つ (A: シミュに LSC モデル化追加・B: perspective+thinlens で物理 cos⁴・C: ISP 補正残差を物理導出) すべて却下，限界と注意点，フォールバック条件 C1-C3 (SHADING_OFF 撮影)，Step 8-13 残差 2.63× の解釈 (LSC 由来ではない別要因，物理モデル誤差の可能性) を明文化．残差 2.63× の解消は今後の課題 (物理モデル精緻化 or SHADING_OFF 撮影で切り分け or 形状相対比較に絞る) ．S3 残作業: TEST_01 への Step 8-13 正式記録・handoff_smtias_lightsim/ 削除． -補足: **実機変更とシミュ側対応の整合マッピングを明文化 (2026-06-02)**．[TECH_08 実機変更とシミュ側対応](docs/05_TECH/TECH_08_実機変更とシミュ側対応.md) として作成．実機側 8 項目変更 (PNG→DNG / AWB OFF / AE OFF / ガンマなし / NR OFF / EDGE OFF / LSC 維持 / LSC 順方向適用) に対するシミュ側 3 層 (Mitsuba シーン定義 α / sm-render β / sm-evaluate γ) の対応をマッピング．**結論: シミュ側で実際に対応が必要だったのは sm-evaluate の config レベルでの OETF 無効化 (#4) と mean アンカー調整 (#3) の 2 項目のみで，他はすべて対応不要 (Mitsuba は per-channel 独立計算で AWB/AE/NR/EDGE 概念なし，orthographic で LSC 自然対応)**．計 15 項目以上で網羅チェック，対応漏れなしを確認．特にガンマ補正は `configs/eval_baseline_dng_target.yaml` で OETF セクションを意図的に書かない形で Step C' にて対応済．**残差 2.63× は ISP 関連の対応漏れではなく，シミュ物理モデル誤差 (反射率精度・LED 配光モデル・メッシュ幾何精度等) が主因**と推定．詳細な切り分けは Step 8-14 以降の物理モデル精緻化として残す． -補足: **「対応不要」を 2 タイプに細分化 (TECH_08 §許容している構造的差異 追加)**．「対応不要」の理由を **タイプ I (本質構造同一・対応概念なし)** = AWB/NR/EDGE/LSC 等と，**タイプ II (構造的差異あり・白板で許容)** = AF (焦点モデル)/絞り口径食/ピクセル積分/センサノイズ/QE 波長依存/シャッター方式/温度依存 に分類．特に AF は実機 perspective+固定焦点 vs シミュ orthographic 無限遠相当という **シミュと実機の構造的な違い**を明示．白板撮影では影響軽微で許容しているが「ゼロ影響」ではない．舌模型評価時や残差精緻化フェーズで再評価対象．Step 8-13 残差 2.63× の主因はタイプ II ではなくシミュ物理モデル誤差と推定する従来結論は維持． -補足: **S3 全体完結 — TEST_01 に Step 8-13 正式記録 + handoff 整理 (2026-06-02)**．[TEST_01 §Step 8-13](docs/06_TEST/TEST_01_キャリブレーション検証履歴.md) に新方針 (実機 DNG+LSC linear) でのシミュ突合を Step 8-1〜8-12 と同フォーマットで正式記録．俯瞰サマリ表に新ターゲット (CoV=0.0695) と Step 8-13 結果 (CoV=0.1826, 残差 2.63×) を追加，過去 2.1× が PNG sRGB ガンマ圧縮による楽観値だった旨も明記．§Step 8-N 候補 (LSC 順方向モデル) を「不採用 — Step 8-13 で方針確定」のヘッダに更新し冒頭注記で経緯を残す (歴史的記録として保持)．`handoff_smtias_lightsim/` ディレクトリは S3 完結のため整理: 参考スクリプト `run_uniformity_dng.py` のみ `reference_measurement/quantitative/reference_scripts/` に移動 (MiniTias-Evaluation 側の正規評価実装 = LSC 順方向適用 + portrait 向き合わせ + ROI 抽出の参考．将来 SHADING_OFF フォールバック発動時の独立検証用)，他は全て SmTIAS-LightSim 側に取り込み済みのため削除．S3 全体 (S2 DNG ローダコピー + Step D radial_min_max 統合 + Step C' 新規 baseline config + TECH_07 LSC 方針 + TECH_08 対応マッピング + Step 8-13 計測 + handoff 整理) 完結．次のキャリブ作業は Step 8-14 以降の物理モデル精緻化 (反射率精度・LED 配光・メッシュ幾何) と TECH_04 フォールバック条件 C1 (SHADING_OFF 撮影) の並行検討． -補足: **LED データシート調査結果を [TECH_09](docs/05_TECH/TECH_09_LEDデータシート調査結果.md) として明文化 (2026-06-02)**．過去 SPEC_03 で「LED Paradise 商品ページにデータシート PDF 掲載なし」「詳細 IES 未提供」と記述していたが，**実は OEM 元 HONGLITRONIC (中国広州，鸿利智汇集团股份有限公司) のデータシートが存在**することが判明．LED Paradise LP-2835D90VW は HONGLITRONIC の HL-A-2835D90VW シリーズ (本命 PDF: lcsc.com/datasheet/C5362368.pdf, SPEC NO B-18-A-0831, 2022-01) の OEM 再販品．Vf 3.1V / 配光角 120° / 単チップ 2835 で物性整合．**配光図 (Page 6) から数値読み取り: ほぼ厳密 Lambertian (cos θ) と一致** (0°→1.0, 30°→0.87, 60°→0.50 FWHM, 80°→0.15, 90°→0)．分光分布 SPD も Page 6 に掲載 (NeutralWhite 4000K, 420nm 鋭ピーク + 500-650nm 蛍光体ブロード)．**重要な含意**: (1) 現状の area light Lambertian モデルはデータシート実測と整合．配光モデル精緻化余地は限定的．(2) **過去 Step 8-11「データシート従順版」(cos^1.2) は実態はデータシート不整合**だった (同等品 Cree/Samsung/Lumileds の典型配光を借用していた)．道理で形状指標が悪化．(3) **Step 8-14 候補 B (LED 配光詳細化) の意義は限定的**．残差 2.63× の主因は配光以外 (反射率精度・幾何・タイプ II 構造的差異・内壁の非 Lambertian 性等)．SPEC_03 の「やや前方凸」記述は HONGLITRONIC データシートでは確認できないので訂正対象．取得 PDF は REFERENCE/datasheets/ に正式配置済 (個人ローカル保持，gitignore 対象)． -補足: **docs/05_TECH と docs/06_TEST に README 追加 (2026-06-02)**．15 ファイル (TECH 9 + TEST 6) がフラットに並んで「散らかり感」あるため，性質分類と navigation を README で提供．05_TECH/README: 🟢 現状方針 (TECH_07-09) と 🔵 議論の経緯 (TECH_01-06) に 2 分類，主な結論サマリ表，経緯マップ図．06_TEST/README: 🟡 キャリブ作業の中核 (TEST_01-03) と 🔵 クローズ済み (TEST_04) と 📋 外部スナップショット (TEST_05/06) に 3 分類，3 ファイル使い分け表．ファイル削除・移動はせずナビゲーションのみ追加． -補足: **残差 2.63× の主因候補を [TECH_10](docs/05_TECH/TECH_10_残差主因候補の網羅整理.md) として網羅整理 (2026-06-02)**．Step 8-14 候補選定の判断材料として作成．ユーザー指摘 3 候補 (LED 配光・反射率・反射回数) + 私の追加候補で 5 カテゴリ 18 項目を網羅．**優先度評価: 🥇 1 位 A1 内壁の非 Lambertian 性 (光沢成分混合 BSDF)** - 「形」を変える可能性が物理的に最も高い，3D プリンタ白フィラメントは完全 Lambertian とは限らない / **🥈 2 位 A8 反射率 R=0.85→0.89** - Step 8-6 物理整合点で多重反射ゲイン 1.36× / **🥉 3 位 A9 max_depth 8→16+** - 後段多重反射の取りこぼし可能性．ユーザー認識 (LED 配光が一番影響) との差分: TECH_09 でデータシート Lambertian 整合済を踏まえて優先度を低下．Step 8-14 候補: β (A1 単独) か δ (A1+A8+A9 全部入り) が筋． -補足: **Step 8-14 候補 γ (D1 ROI 整合の再確認) 完了 — クリア (2026-06-02)**．他の物理モデル変更に進む前の事前確認として実施．設定変更ゼロで，既存設定の数値検証のみ．シミュ ROI (24, 37, 464, 450) の物理範囲 (X∈[-45.31, +45.31] mm × Y∈[-46.92, +44.48] mm，幅 90.63×91.41 mm) と実機 ROI (539, 1015, 1400, 1409) の物理範囲 (実機 PNG の評価板黒縁検出から物理分解能 0.0654 mm/px を確定 → 幅 91.54×92.13 mm) を比較した結果，**物理サイズ差 < 1%・中心位置差 < 1 mm で整合**．3 列パネル `output/_slide_panels/roi_alignment_check.png` (①実機画像 + 評価板境界・実機 ROI / ②シミュ輝度マップ + 評価板境界・シミュ ROI / ③物理座標系で重ね合わせ) でも視覚確認．**残差 2.63× の主因は ROI 整合ではない**ことが確定．過去の設定者 (`scripts/select_white_board.py` GUI 選択 + シミュ ortho_scale 設計値) が物理整合性を意識して ROI を揃えていたことが裏付けられた．副次発見: 評価板は実機画像中央から下方向に約 4.2 mm (65 px) オフセット配置されているが (取付位置のミリ精度差)，ROI もそのオフセットに沿って選択されているため物理領域として整合．次のアクション: 残候補 β (A1 単独) / α (A8+A9) / δ (β+α 全部入り) を選択して Step 8-14 を実施． -補足: **Step 8-14 候補 β (A1 内壁の非 Lambertian 性) 完了 — クリア (2026-06-02)**．候補リスト 🥇 1 位だった A1 を 3×3 グリッド感度分析で検証．スキーマ拡張 (`BlendBSDFConfig` + `RoughConductorBSDFConfig` 追加，`MaterialConfig` Union 拡張，forward reference + `model_rebuild()`) と `materials.py` 再帰変換 (`_build_bsdf_dict`) を新規実装．テンプレ `configs/scene_baseline_blend.yaml` + スイープスクリプト `scripts/sweep_blend_bsdf.py` + 比較パネルスクリプト `scripts/build_blend_bsdf_panel.py`．新規テスト 89 件追加 (608 → 697 全通過)．**weight ∈ {0.05, 0.15, 0.30} × α ∈ {0.1, 0.3, 0.6} の 9 ジョブ実走 (75.5 分)**．結果: ベースライン純 diffuse (CoV=0.1826, 勾配=24.65%, C/P=1.327, 動径 min/max=0.615) と比較して **全 9 パターンが悪化または不変** (最良 w=0.05/α=0.6 で CoV=0.1851，最悪 w=0.30/α=0.1 で CoV=0.2433)．実機 (CoV=0.0695) 方向と **逆方向に動く**．「形」は w=0.30 で下端中央に 2 つの specular 集中スポットが顕在化．物理的解釈: 純 Lambertian は cos 重み散乱で多重反射の均一化作用が最大．specular 成分は特定方向に光を集中させ均一化を阻害．**3D プリンタ白フィラメントは完全 Lambertian として扱うのが実機挙動に近い近似** と判明 (TECH_09 LED Lambertian 整合と並ぶ「物理モデル妥当性の裏付け」)．**A1 は残差 2.63× の主因ではない**ことが確定．TECH_10 優先順位を更新: A1 を「クリア」化，🥇 1 位 A8 反射率 R=0.89 / 🥈 2 位 A9 max_depth 16+ / 🥉 3 位 B1 幾何精度 に繰り上げ．副次成果: スキーマ層に `blendbsdf` + `roughconductor` のサポートが入り，今後の物理モデル試行で再利用可能．比較パネル `output/_slide_panels/blend_bsdf_sweep.png` + `blend_bsdf_metrics.png`，全 9 ジョブ集約 `output/blend_sweep/summary.csv`．[TECH_10 § A1 検証結果](docs/05_TECH/TECH_10_残差主因候補の網羅整理.md#a1-検証結果2026-06-02-完了) / [TEST_01 § Step 8-14 候補 β](docs/06_TEST/TEST_01_キャリブレーション検証履歴.md#step-8-14-候補-β-a1-内壁の非-lambertian-性--混合-bsdf-感度分析) / [SPEC_02 materials](docs/04_SPEC/SPEC_02_シーン定義仕様.md#materials) 参照．次のアクション: Step 8-14 候補 α (A8 R=0.89 + A9 depth=16) の組み合わせ実施． -補足: **LED グループ別 sanity check 完了 — TEST_07 として報告 (2026-06-03)**．Step 8 系キャリブの主軸ではなく「シミュが下/右/左の 3 LED 基板を物理位置どおりに独立にモデル化できているか」の基礎健全性確認．`scripts/sanity_led_groups.py` で各基板の 6 LED だけを ON にした一時 YAML を生成 → 3 ジョブ sm-render (約 25 分) → 比較パネル．結果: **方向性 ✓** (bottom は下端中央/right は右側面寄り/left は左側面寄り)，**左右対称性 ✓** (right mean=47.10 vs left mean=47.08)，**量的バランスは bottom が right/left の 2.10× で強い**．ユーザー観察「bottom は上下の島，right/left は中心の円」は LED 配置で説明: bottom LED は評価板の下端真下に X 中央寄り集中 → 直接光が広範囲を叩く / right/left LED は側面外側で Y 中央付近に分散 → 直接光は端のみ・中央は多重反射経由 → 「直接光寄与が大きい bottom」vs「多重反射寄与が大きい right/left」の構造的違い．**線形性検証は別途未実施**（既存 `output/baseline/luminance.npy` が Step 8-1 時点の古いもので和との比較不可．Mitsuba は理論線形なので baseline 再生成で一致見込み）．副次発見: 実機の right (Y∈[-25,+3]) と left (Y∈[-33,-5]) は **完全な左右対称設計ではない**（Fusion STL 実位置と整合）．[TEST_07 LED グループ別動作確認](docs/06_TEST/TEST_07_LEDグループ別動作確認.md) 参照．**シミュレーションは 3 つの照明源を物理位置どおりに独立にモデル化できている**ことが確定し，Step 8 系の残差 2.63× 議論の前提が担保された． -補足: **scene_baseline.yaml の max_depth を 8 → 16 へ更新 (2026-06-03)**．Step 8-14 候補 α 前半の結論「d=16 が実用収束点」を反映．SPEC_03 の既知差分 #6 (未対処の max_depth=8) を解消．SPEC_03 の関連箇所 4 箇所 (パラメータ表 / 多重反射の説明 / 制限セクション / 既知差分一覧) を一括更新．TEST_02 の `output/baseline/` 行に「d=8 時代の古い結果」注記を追加（output/baseline/luminance.npy は 2026-05-18 生成で d=8、現 scene_baseline.yaml の d=16 とは不整合．必要時に再生成）．影響: 今後の sm-render は自動的に d=16 で実行され、理論累積 92.6% を取り込む．計算時間は d=8 の約 2× (8.5 分 → 17 分) に増加するが、形状指標 4 つすべてが d=8 時代より実機方向に改善 (CoV 0.1817 → 0.1604, 勾配 24.01% → 20.59%)．次のスイープ系 (A8 反射率, A10 サブサーフェス散乱等) は自動的に d=16 ベースで実行される． -補足: **Step 8-14 候補 ξ (A2/A3 LED 配光 cutoff スイープ) 完了 — 配光が形改善の本物の候補として初実証 (2026-06-03)**．ユーザー要請「配光条件を変えてどのような変化が起こるかの実験．データシートに合わせる必要なく，照明の影響を調べるための実験」に基づき，`scripts/sweep_led_distribution.py` で spot emitter の cutoff_angle を {30°, 60°, 90°, 120°, 150°} で 5 値スイープ．`configs/scene_baseline_spot.yaml` (Step 8-10 で作成) をテンプレに beam_width = cutoff/3 で連動，max_depth を 16 に更新．約 85 分．**重要な 2 つの発見**: ① **「area light → spot」のステップが本質的** — area (Lambertian) の angular_ratio=0.4536 → spot (どの cutoff でも) 0.34〜0.36 へ **25% 大幅低下** (実機方向)．② **cutoff スイープ内 (30°→150°) では effect 限定的** — angular_ratio は 0.338→0.356 と +0.018 のみ．**A8 と真逆のパターン**: 数値悪化 (CoV +3〜11%) するが形改善 (angular_ratio -25%)．これは「数値の偽物の一致」(A8) と対をなす「形改善の本物の候補」初実証．物理的解釈: spot は +Z 軸方向にしか光を出さない → 内壁に当たる成分が減り直接光増 → LED 直下の明点 → X 方向波打ち → 半径方向ばらつき支配 (angular_ratio 減)．area は半球全方向に拡散光 → 多重反射 ambient 支配 → Y 軸勾配．**spot にすると「内壁多重反射 ambient < 直接光」に傾き，評価板の照度分布が LED 配置パターンを直接反映**．副次発見: 数値最良点 (cutoff=90°, CoV=0.165) と形最良点 (cutoff=30°, ang_ratio=0.338) が異なる→ キャリブで「何を優先するか」議論を明確化．**TECH_10 優先順位を再更新**: A2/A3/ξ を「形改善候補」へ昇格．B1 と並列の本筋候補 (本検証以前は「データシート Lambertian 整合済」として 4 位だった)．[TECH_10 § ξ 検証結果](docs/05_TECH/TECH_10_残差主因候補の網羅整理.md#ξ-検証結果2026-06-03-完了) / [TEST_01 § Step 8-14 候補 ξ](docs/06_TEST/TEST_01_キャリブレーション検証履歴.md#step-8-14-候補-ξ-a2a3-led-配光-cutoff_angle-5-値スイープ-30-60-90-120-150) 参照．次のアクション: emitter のより本質的バリエーション (cos^n / IES / 軸ティルト ζ) / 配光と他候補の組み合わせ (spot + R 調整 + max_depth で形 + 数値両立) / B1 筐体幾何精度． -補足: **Step 8-14 候補 α 後半 (A8 反射率スイープ) 完了 — 数値改善のみ・形は逆効果 / 「数値の偽物の一致」の初の定量実証 (2026-06-03)**．`scripts/sweep_reflectance.py` で d=16 新基準のもと R ∈ {0.75, 0.80, 0.85, 0.89, 0.92} を 5 値スイープ．新指標 (shape_metrics) を初めて感度分析に投入．結果: 既存 4 指標 (CoV/勾配/C/P/動径 min/max) は単調改善 (R=0.75 → 0.92 で CoV 0.186→0.142 で残差 24% 縮小，勾配 24.7→17.7%，rmin/max 0.620→0.731) するが，**新指標 angular_ratio は 0.408→0.494 で実機方向と逆に増加**．実機は中央ピーク楕円 (同心円的 = angular_ratio 小予想) なので **形は実機から遠ざかる**．TECH_11 で予想していた「数値の偽物の一致」を初めて現実データで実証．物理的解釈: R 上昇で ambient 増 → 半径方向の偏りは圧縮されるが角度方向のばらつきは相対的に圧縮されにくい → 「半径 var / 角度 var」バランス崩れ angular_ratio 増加．「Y 単調勾配の contrast を緩める代わりに角度方向のムラを相対的に強調」する効果．**A1/A9 検証より強い発見**: 「均一化フィルタ系は形を変えない」を超えて「数値改善が形を逆方向に動かす」ケースの実証．TECH_10 優先順位を再更新: A8 を「数値改善のみクリア」化．**形改善の本筋は B1 筐体幾何精度に最終確定**（A1/A8/A9 すべてクリア済で構造的再配分系のみ残る）．副次発見: R=0.85 の CoV=0.1604 が max_depth スイープ d=16 と完全一致 (別 sweep 間の数値整合性 OK)．centroid_y_norm 0.045→0.036, eccentricity 0.444→0.414 はわずか改善 (但し angular_ratio 悪化が支配)．新指標を導入していなければ気づけない発見であり、形状指標見直し (TECH_11) の正当性が定量データで裏付けられた．[TECH_10 § A8 検証結果](docs/05_TECH/TECH_10_残差主因候補の網羅整理.md#a8-検証結果2026-06-03-完了) / [TEST_01 § Step 8-14 候補 α 後半](docs/06_TEST/TEST_01_キャリブレーション検証履歴.md#step-8-14-候補-α-後半-a8-反射率-5-値スイープ-r075-080-085-089-092) 参照．次のアクション: **B1 筐体幾何精度の検討 / A10 サブサーフェス散乱 / ζ LED ティルト** の構造的再配分系候補に進む． -補足: **Step 8-14 候補 α 前半 (A9 max_depth スイープ) 完了 — 数値改善のみクリア・形不変 (2026-06-03)**．ユーザー仮説「現状 d=8 では 0.85^8≈0.27 で取りこぼし大．0.01 未満まで増やすべき」を 5 値スイープ {8, 12, 16, 20, 28} で検証．`scripts/sweep_max_depth.py` (約 85 分) + `scripts/build_max_depth_panel.py` (収束カーブ + 数値表) を新規実装．結果: 全 4 形状指標 (CoV/勾配/C/P/動径 min/max) が **単調に実機方向に改善**．d=8→28 で **CoV=0.1817→0.1583** (残差 20.9% 縮小)，勾配=24.01→20.24% (24.1%)，C/P=1.316→1.254 (27.6%)，動径 min/max=0.628→0.689 (26.3%)．mean は 207.82 で固定 (アンカー正規化)．**実用的な収束は d=16 で達成** (d=16→28 で CoV 1.3% のみ動く)．理論累積 R^n より早く収束は「直接光と初期反射が支配的，後段は ambient のみ」の物理直感と整合．**「形」は完全に不変** (3 種類のパネル shared/independent/mean=1 正規化 全てで Y 軸単調勾配のまま contrast が緩むだけ)．物理的解釈: 多重反射は **空間的に均一な ambient 成分**で，これを足しても暗/明領域の絶対差は縮むが空間配置は不変．「LED が下にしかない」配置の非対称性は除去不能．これは TEST_03「Step 8-1〜8-7 で形は全く変わっていない」と整合．**ユーザー仮説の評価**: 方向性は完全に正しい (21-28% 残差縮小)．ただし実用収束は d=16 (理論累積より早い)．d=28 まで増やしても追加改善 1% のみ．実機 (CoV=0.0695) には届かず，**残る残差は形改善で詰める必要**．**TECH_10 優先順位を再更新**: A9 を「数値改善のみクリア」化．**形改善の本筋候補は B1 幾何精度に集約**．A8 反射率 R=0.89 は数値改善目的では有効だが形改善は予想薄．新規候補として ε B1 と ζ LED 軸ティルトを追加．新キャリブベースライン候補: **d=16** (現状 d=8 は理論累積の 72.7% で取りこぼし大)．副次成果: スイープ + 収束カーブ + 形比較パネル (`shape.png` 上下 2 段, `relative.png` mean=1) のテンプレが整備され今後の感度分析に流用可能．[TECH_10 § A9 検証結果](docs/05_TECH/TECH_10_残差主因候補の網羅整理.md#a9-検証結果2026-06-03-完了) / [TEST_01 § Step 8-14 候補 α 前半](docs/06_TEST/TEST_01_キャリブレーション検証履歴.md#step-8-14-候補-α-前半-a9-max_depth-スイープ-8-12-16-20-28) 参照．次のアクション: 候補 ε B1 筐体幾何精度 / 候補 ζ LED 軸方向ティルト仮説 のいずれかを実施． -補足: **形状指標の本質的見直しと新指標導入 (2026-06-03)**．Step 8-14 で「A9 max_depth スイープで数値が実機方向に動いても形は全く変わらない」「A1 非 Lambertian でも形は実機に近づかない」が続けて確定したため，ユーザー指摘「現状 4 指標は不均一性の絶対量しか測れず，Y 軸単調勾配と中央ピーク楕円を構造的に区別できない」に対応する **形を直接評価する 5 指標** を追加実装．`src/sm_tias_lightsim/evaluation/shape_metrics.py` (新規): `calc_intensity_centroid`（輝度重心 5 値）/ `calc_angular_radial_decomposition`（極座標分解，angular_ratio: 0=同心円, 1=方向依存）/ `calc_ssim`（scikit-image 依存, shape_reference 指定時）/ `calc_ncc`（正規化相関係数）/ `calc_intensity_pca`（weighted PCA 主軸・eccentricity）の純関数 5 つ．`MetricsConfig` に `shape_metrics: bool = False` / `shape_reference: str | None = None` を追加（後方互換）．`cli/evaluate.py` に `_run_shape_metrics` 関数追加 + コンソールサマリ拡張．`configs/eval_baseline_dng_target_shape.yaml` を新規作成 (shape_metrics=true, shape_reference=null)．`pyproject.toml` に `scikit-image>=0.21.0` を追加．[TECH_11 形状指標の見直しと新指標導入](docs/05_TECH/TECH_11_形状指標の見直しと新指標導入.md) で背景・計算式・シミュ vs 実機予想値・過去判断への遡及的注記を記録．TEST_01 俯瞰サマリ上に「形状指標は絶対量のみ測る」注記を追加．TECH_10 A9/A1 検証結果に「新指標での再評価が必要」注記を追加．今後の評価方針: **数値指標 4 + 形指標 5 + 視覚比較の 3 軸評価**で「数値改善のみで形が変わらない候補」と「形を変えうる候補」を明確に区別する． +最新: フェーズ 7（実装）— Step 8 基準設計キャリブレーションの **Step 8-14（物理モデル精緻化）** 進行中．A1 非 Lambertian / A8 反射率 / A9 max_depth はクリア（数値改善のみ or 逆効果），LED 配光(ξ)が形改善の本物候補と判明，**形改善の本筋は B1 筐体幾何精度に確定**（実機 CoV=0.0695 に対しシミュ CoV=0.1826，残差 2.63×）．詳細な経緯・設計判断・失敗パターンは [docs/PROGRESS.md](docs/PROGRESS.md)． 実装済みモジュール: - `src/sm_tias_lightsim/uniformity.py` — Rec.709 輝度変換 + CoV/std/max-min（MiniTias-Evaluation コピー） @@ -74,7 +35,7 @@ - `src/sm_tias_lightsim/evaluation/dng_loader.py` — DNG 読み込みモジュール．MiniTias-Evaluation `src/io/dng_loader.py` を SmTIAS-LightSim にコピーしたもの (オリジナルは MiniTias-Evaluation 側で管理．バグ修正・機能追加はそちらで反映)．主要 API: `load_image_dng(path, demosaic, black_level, output_format)`．`output_format` は `rgb_float32` / `luma_float32` / `rgb_uint8`．linear 系出力 (`rgb_float32` / `luma_float32`) は `output_color=raw` でカラーマトリクス非適用・per-channel 比例性保持．`gamma=(1,1) + no_auto_bright=True + use_camera_wb=False + user_wb=[1,1,1,1]` で linear raw を保つ．依存: `rawpy>=0.21.0` - `src/sm_tias_lightsim/evaluation/radial.py` — 20 ビン放射状輝度プロファイル．既存 `calc_radial_profile` に加えて MiniTias-Evaluation `src/analysis/spatial.py:calc_radial_min_max_ratio` をマージ．動径 min/max 比 (20 点輪帯平均) は画素単位 max/min よりノイズに対しロバスト．nan ビン除外を移植時に補強 (既存 `calc_radial_profile` は空ビンを nan で返す) - `src/sm_tias_lightsim/evaluation/shape_metrics.py` — 輝度分布「形」評価指標モジュール（新規）．現状 CoV/勾配/C/P/動径 min/max は不均一性の絶対量しか測れず，Y 軸単調勾配と中央ピーク楕円を構造的に区別できない問題を解決する 5 つの純関数: `calc_intensity_centroid`（輝度重心，5 値）/ `calc_angular_radial_decomposition`（極座標分解，angular_ratio が 0=同心円〜1=方向依存，3 値）/ `calc_ssim`（構造的類似度，scikit-image 依存，shape_reference 指定時のみ）/ `calc_ncc`（正規化相関係数，絶対輝度不変）/ `calc_intensity_pca`（weighted PCA で主軸角度と eccentricity，4 値）．mask 省略可能，完全均一画像で angular_ratio/NCC は NaN を返す．`MetricsConfig.shape_metrics=true` / `shape_reference` フィールドで有効化，後方互換保持．依存追加: `scikit-image>=0.21.0`．詳細: [TECH_11 形状指標の見直し](docs/05_TECH/TECH_11_形状指標の見直しと新指標導入.md) -※ ステップ完了時にここを更新すること． +※ 本欄は**最新ステップ 1 行のみ上書き更新**．詳細な進捗履歴（動機・設計判断・失敗パターン）は [docs/PROGRESS.md](docs/PROGRESS.md) に追記する．運用ルールは GUIDE_05「進捗記録の運用ルール（CLAUDE.md / PROGRESS.md）」を参照． ## 必須ルール（コード実装時） @@ -84,6 +45,8 @@ - ブランチ名・コミットメッセージの書式は GUIDE_04 に従う - コミットは `/commit` を使用する（push・PR 作成は `/commit push`） +- **`/commit` はユーザーが明示的に指示した時のみ実行する．Claude が自発的に `/commit` や `git commit` を呼んではならない**（`/implement` 完了後も，案内するだけで自分ではコミットしない） + - **例外**: `/auto-refactor`（無人運転のリファクタ／ドキュメント整理ループ）はユーザー承認済みの例外として `refactor/` 専用ブランチに自律コミットする．ただし push・PR・マージ・`main` への操作はしない（取り込みは人間が `/commit push` 等で行う） ### エージェントチーム（GUIDE_05 準拠） diff --git "a/docs/01_GUIDE/GUIDE_01_\343\203\227\343\203\255\343\202\270\343\202\247\343\202\257\343\203\210\347\253\213\343\201\241\344\270\212\343\201\222\343\203\225\343\203\255\343\203\274.md" "b/docs/01_GUIDE/GUIDE_01_\343\203\227\343\203\255\343\202\270\343\202\247\343\202\257\343\203\210\347\253\213\343\201\241\344\270\212\343\201\222\343\203\225\343\203\255\343\203\274.md" index acdb976..a6f9a0c 100644 --- "a/docs/01_GUIDE/GUIDE_01_\343\203\227\343\203\255\343\202\270\343\202\247\343\202\257\343\203\210\347\253\213\343\201\241\344\270\212\343\201\222\343\203\225\343\203\255\343\203\274.md" +++ "b/docs/01_GUIDE/GUIDE_01_\343\203\227\343\203\255\343\202\270\343\202\247\343\202\257\343\203\210\347\253\213\343\201\241\344\270\212\343\201\222\343\203\225\343\203\255\343\203\274.md" @@ -15,6 +15,8 @@ | 開発計画 | ステップを分割し，開発順序を決める | `PLAN_02_開発ステップ.md` | | 実装開始 | 開発計画に沿って実装を進める | ソースコード | +※ 立ち上げフローで作成するのは `01_GUIDE / 02_ENV / 03_PLAN / 04_SPEC` カテゴリの成果物のみ．`05_TECH`（技術設計）・`06_TEST`（テスト）は実装フェーズで必要になった時点で作成し，立ち上げ時に空フォルダを作らない． + ## 方針決定 (Direction) プロジェクトの全体像を明確にする． @@ -92,17 +94,18 @@ ### 記載すべき内容 - **プロジェクト概要**: プロジェクト名，目的，技術スタックの要約 -- **開発進捗**: 現在のステップ，次にやること +- **開発進捗**: 現在のステップ（最新 1 行のみ）．詳細な進捗履歴は `docs/PROGRESS.md` に追記する（[GUIDE_05](GUIDE_05_エージェント運用ルール.md) の「進捗記録の運用ルール（CLAUDE.md / PROGRESS.md）」参照） - **必須ルール**: AI が実装時に必ず守るべきルール（コーディング規約，コミット前チェック等の要点） - **ドキュメント一覧**: docs/ 内のファイルへの参照パス ### 更新タイミング -- ステップの完了時に開発進捗を更新する +- ステップの完了時に開発進捗を更新する（CLAUDE.md は最新 1 行に上書き，`docs/PROGRESS.md` は末尾に追記） - ドキュメントの追加・削除・リネーム時に参照パスを更新する - 必須ルールに変更があった場合に反映する ### 運用上の注意 - CLAUDE.md は AI が毎回読み込むため，簡潔に保つ．詳細は docs/ のドキュメントに委ね，CLAUDE.md には要点と参照先のみ記載する． +- 進捗記録は二段構成（CLAUDE.md = 最新 1 行 / `docs/PROGRESS.md` = 追記型フルログ）で管理する．詳細は [GUIDE_05](GUIDE_05_エージェント運用ルール.md) を参照． - プロジェクト固有のルールが増えたら，docs/ に独立ファイルとして切り出し，CLAUDE.md からはリンクで参照する． diff --git "a/docs/01_GUIDE/GUIDE_05_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" "b/docs/01_GUIDE/GUIDE_05_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" index 9a30190..ae5ea44 100644 --- "a/docs/01_GUIDE/GUIDE_05_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" +++ "b/docs/01_GUIDE/GUIDE_05_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" @@ -51,7 +51,7 @@ │ テスト再実行で挙動が変わっていないことを保証 │ ├─ Phase 4 ──▶ ドキュメント更新 - │ docs/ と CLAUDE.md を必要に応じて更新 + │ docs/, CLAUDE.md, docs/PROGRESS.md を必要に応じて更新 │ 更新がある場合のみ人間の確認を挟む │ 結果を .claude/commit-context.md に書き出す │ @@ -93,21 +93,21 @@ ### Phase 4: ドキュメント更新 (Documentation) -Phase 3 完了後，実装内容に応じて `docs/` と `CLAUDE.md` を更新する． +Phase 3 完了後，実装内容に応じて `docs/`, `CLAUDE.md`, `docs/PROGRESS.md` を更新する． - **チェック観点**: - API・データ構造の変更 → `docs/04_SPEC/` の該当仕様を更新 - 環境・依存関係の変更 → `docs/02_ENV/` を更新 - - 開発ステップの進捗 → `docs/03_PLAN/` や `CLAUDE.md` の進捗欄を更新 + - 開発ステップの進捗 → `docs/03_PLAN/` や進捗記録（`CLAUDE.md` の進捗欄＋ `docs/PROGRESS.md`）を更新（書式は本ガイドの「進捗記録の運用ルール（CLAUDE.md / PROGRESS.md）」に従う．`git log` で取れる詳細は書かない） - 規約・運用ルールの変更 → `docs/01_GUIDE/` を更新 - **該当なし**: ドキュメント更新が不要な変更（軽微なバグ修正，リファクタリングのみ等）はスキップ可． - **更新がある場合のみ**人間の確認を挟む．更新不要の場合は確認なしで完了処理に進む． -- **コミットコンテキストの書き出し**: Phase 4 の結果（更新の有無と理由）を `.claude/commit-context.md` に書き出す．このファイルは `/commit` が参照し，docs/CLAUDE.md の更新漏れチェックをスキップするために使う（`.gitignore` 対象）． +- **コミットコンテキストの書き出し**: Phase 4 の結果（更新の有無と理由）を `.claude/commit-context.md` に書き出す．このファイルは `/commit` が参照し，`docs/`, `CLAUDE.md`, `docs/PROGRESS.md` の更新漏れチェックをスキップするために使う（`.gitignore` 対象）． ### 完了処理 - `/implement` はコミットを行わない．完了後は `/commit` でコミットする． -- `/commit` は `.claude/commit-context.md` が存在する場合，docs/CLAUDE.md の更新漏れチェックをスキップする．存在しない場合（`/implement` を経由していない場合）は警告のみ行う． +- `/commit` は `.claude/commit-context.md` が存在する場合，`docs/`, `CLAUDE.md`, `docs/PROGRESS.md` の更新漏れチェックをスキップする．存在しない場合（`/implement` を経由していない場合）は警告のみ行う． ## コンテキスト受け渡し (Context Passing) @@ -135,3 +135,60 @@ パイプライン完了後は `/commit` でコミットする．コミットメッセージのタグ等は [GUIDE_04](GUIDE_04_Git運用ルール.md) に従う． ※ リファクタリングとテストは実装と一体の成果物として，まとめてコミットする．必要に応じて分割コミットも可． + +※ **例外（無人運転）**: `/auto-refactor` は CLAUDE.md の「`/commit` 自発実行禁止」ルールに対するユーザー承認済みの例外として，`refactor/` 専用ブランチに自律コミットする．push・PR・マージ・`main` への操作は行わず，取り込み可否は人間が判断する． + +## 進捗記録の運用ルール（CLAUDE.md / PROGRESS.md） + +進捗記録は **2 ファイルの二段構成**で管理する．Phase 4 や `/setup` 中断時にこれらを更新する． + +| ファイル | 役割 | 更新方法 | +| --- | --- | --- | +| `CLAUDE.md` の「開発進捗」セクション | **最新ステップ 1 行のみ**（毎ターン読み込まれる薄い目印） | 上書き | +| `docs/PROGRESS.md` | **追記型のフル進捗ログ**（動機・設計判断・失敗パターン含む） | 末尾に追記 | + +**背景**: CLAUDE.md は毎ターン読み込まれるため，追記型運用にするとコンテキスト圧迫の原因になる．一方で進捗の経緯・失敗パターン・設計判断はタスクを跨いで価値があるため捨てたくない．そこで「常に読まれる薄いポインタ（CLAUDE.md）」と「必要な時だけ読む厚いログ（PROGRESS.md）」に分離する．関数名・引数・テスト件数等の実装詳細は `git log` とコミットメッセージに完全な形で残るため，どちらにも書かない． + +### CLAUDE.md「開発進捗」の書き方 + +- **最新 1 行のみ**．古い行は上書きで消す（履歴は PROGRESS.md に残るので消えてよい） +- 基本形式: `最新: <ステップ見出し>` +- 関数名・テスト件数・実装手順詳細は書かない（PROGRESS.md と `git log` に任せる） + +### docs/PROGRESS.md の書き方 + +`docs/PROGRESS.md` は追記型．最新エントリを**末尾に追記**する（時系列順．古いものが上，新しいものが下）． + +**書く（PROGRESS.md に残す価値が高いもの）**: + +以下は PROGRESS.md に置く価値があるが，全て書く必要はない．シンプルなステップなら状況の 1 行だけで十分．書くことが少ない時に無理に伸ばさない． + +- 状況: 何が完了したか（1 行） +- 動機・原因: なぜそれをやったか（既存の問題点・要件変更・前バージョンの欠点など） +- 重要な設計判断: 他案との比較が必要な場合のみ．「A 案ではなく B 案を選んだ理由」が将来の判断材料になるとき +- 失敗パターンの圧縮サマリ: 「① X 案 → Y で破綻 / ② Z 案で解決」のような 1〜2 行．同じ轍を踏まないための知識として残す．試行錯誤を時系列で全部書かず，本質的に異なるアプローチの失敗だけを並列項目として記録する +- 未実装・後段: 「次に何をすべきか」を思い出すための短いメモ + +**書かない（コミットメッセージと `git log` に任せる）**: + +以下は `git log ` または `git show ` で完全な情報が取れる．PROGRESS.md に書くと重複・陳腐化する． + +- 関数名・引数・型シグネチャ +- テスト件数の内訳（合計件数のみなら可だが数字は陳腐化するので省略推奨） +- リファクタリングの手順詳細 +- 撤去・新規追加の関数リスト +- 具体的な定数値・閾値（設計判断の核心に関わるものを除く） +- 数値範囲の細部（実装パラメータ等） +- 後方互換性の細かい仕様 +- 「全テスト N passed」の報告（pass している前提のため不要） + +**長さと書式**: + +- 1 エントリの長さは内容次第で可変．書くことが少なければ **1 行で十分**．複数系統の作業を 1 ステップにまとめた等で必要なら長くなってもよい．無理に伸ばさず無理に削らず，「未来の自分（または他人）が辿れるか」だけを基準にする +- 基本形式: `- [x] **<簡潔な見出し>**: <1〜2 文の要約>`．必要に応じて下に動機・設計判断・失敗パターンを 1〜2 行ずつ追加 +- 太字は**見出しに使う**（目次の項目として目立たせる）．本文中で多用しない +- 長い箇条書きを避ける．箇条書きは「失敗パターン ① ② ③」のような本質的に異なる選択肢の並列項目に限定する + +**既存エントリの長文化に気付いたとき**: + +過去のエントリで「詳細をベタ書きしていて目次として機能しなくなっている」ものを見つけたら，ユーザーに圧縮を提案する．自動で削らない（背景情報の価値判断はユーザーが行う）．提案時は「この情報は `git log` にあるので削れる / これは失敗パターンなので残すべき」のように切り分けて示すこと． diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md new file mode 100644 index 0000000..a701f0c --- /dev/null +++ b/docs/PROGRESS.md @@ -0,0 +1,59 @@ +# 開発進捗ログ + + + +> 以下は 2026-06-25 のテンプレート同期（進捗ログ 2 段構成への移行）に伴い，CLAUDE.md「開発進捗」セクションに蓄積していた `補足:` ログを移行したもの．**移行時点の文面をそのまま保持**している（古い記述・関数名等も歴史的記録として保持．今後の新規エントリは GUIDE_05 の書式に従い，`git log` で取れる詳細は書かない）． + +## フェーズ 7（実装）— Step 8 基準設計キャリブレーション + +現在の進捗（移行時点）: フェーズ 7（実装）— Step 1〜7 完了，Step 8（基準設計キャリブレーション）進行中． + +Step 8 進捗（初期サマリ）: spp 校正（128→1024、ノイズ/物理差を切り分け）→ 反射率スイープ（0.75〜0.92、弱い二次レバーと判明）→ **手法訂正**: シミュ linear と実測 sRGB を直接突合していた交絡を発見．標準 sRGB OETF 順方向適用＋実測 mean アンカーで見かけ差の **約 2/3 が符号化ドメイン不一致**だったと判明．寄与順は OETF（最大）＞ ISP レンズシェーディング（残差主因候補）＞ 反射率（小）．残差 1.6〜1.9 倍は調整せず正直に保持．副次: max_depth=8 は勾配を過大評価（キャリブは depth≥12）．→ **OETF 順方向適用を sm-evaluate へ正規実装完了**（`evaluation/oetf.py` + `EvaluationConfig.oetf`、baseline 有効化・real 非適用、後方互換、参照実装と数値一致テスト済み）．[SPEC_03「キャリブレーション経過」参照](04_SPEC/SPEC_03_基準設計の物理構成.md)． + +### 時系列ログ（古い順 → 新しい順） + +- **3D ビュー改善**: 内部キャリブ調整は一旦中断し、**シミュ結果の見せ方（3D ビュー）改善**を実施．評価板実レンダ投影 → **path ベイク（`baker.py` mode="path"、多重反射込み per-face、scalar_rgb）** 追加 → 全メッシュ統一着色（共有 lit-clim・log・単一カラーバー）を既定化、`--render` は任意のテクスチャ投影オプション（評価板 E=π·L/ρ で同一スケール）、`--bake-cache` で 1 回計算→以後即時、`--opacity`/`--hide-below`/`--bake-smooth`/`--bake-scale` を追加．さらに **path ベイク max_depth を render 設定から独立（`--bake-max-depth`、既定 16）**＝後段多重反射を積分、**幾何カリング（`--cull-outward` 既定 ON、外向き ≈0 面を非描画）**＝暗殻の濁り/見かけ段差を解消、マーカー個別非表示フラグ、を追加．実装完了． + - 既知の制約（受容済み）: per-face ベイクはメッシュ境界の継ぎ目・粗メッシュのブロック感・低 samples の MC ノイズ・scalar_rgb の遅さ（高 samples 非現実的）あり．精細な評価は 2D `sm-evaluate` で行う（不変）．隣接内壁の見かけ段差は調査の結果「外向き ≈0 面の混在」が主因と判明＝幾何カリングで解消（内壁照度自体は物理どおりほぼ均一）． + - 次のアクション（別タスク）: シーム/粒状感の解消には全メッシュ UV 統合＋シームレスライトマップベイク（別プロジェクト規模）．必要時に別途 `/implement`．path ベイク高速化（wavefront/GPU）も別タスク． +- **実機搭載 LED の物性確定**（LED Paradise LP-2835D90VW / Ra98 SunLightLED 2835 4000K、Vf 3.1V・If 60mA・Φv 16–19 lm @60mA・配光角 120°・規格通り 60mA 駆動前提）．規格値から独立推定した radiance ≈ 2030 W/(m²·sr) は現状校正値 2807 と 1.38× 差で、反射率 0.85→0.89 への調整で物理範囲内に説明可能．既知差分 #3（LED 実 W 値未検証）クローズ．**形状指標への影響なし**（線形ゲイン）．配光は厳密 Lambertian 仮定継続（詳細 IES 未提供、実 SMD 2835 のやや前方凸性は ISP LSC と打ち消し合う近似として現状妥当）．詳細: [SPEC_03 LED セクション](04_SPEC/SPEC_03_基準設計の物理構成.md#led光源)． +- **輝度マップ「形」の追跡を導入**（[TEST_03 輝度マップ形状追跡](06_TEST/TEST_03_輝度マップ形状追跡.md) + `scripts/build_luminance_evolution_panel.py`）．重要な発見: **これまでの全 7 改善ステップ (8-1〜8-7) で輝度マップの「形」は全く変わっていない**．OETF は単調変換で形を変えず，発光面サイズ変更も形を変えない．**実機は中央付近にピークを持つ楕円状，シミュは下端のみ明の Y 軸単調勾配**．**LSC モデル化は「数値残差縮小」と「形の構造的改善」の両方を担う唯一の改善候補**．以後の改善判断は「数値 + 形」の 2 軸で行う． +- **Step 8-8 完了**: linear 評価モードに mean 揃え正規化を導入（`evaluation/normalize.py` の `apply_mean_anchor` + `EvaluationConfig.normalization` スキーマ + CLI 統合 + OETF 排他バリデーション）．OETF 露出アンカー（Step 8-3）と同じ思想を linear ドメインに対称展開．`configs/eval_baseline_linear.yaml` で有効化（target_mean=146.7146）．形状指標 (CoV/勾配/C/P/max-min) は厳密不変，mean のみ target_mean に揃う．動作確認: α=0.961934 で baseline luminance.npy が mean=146.7146, CoV=0.182577 で評価可能． +- **Step 8-9 完了**: LED 18 個の位置を Fusion 360 設計 STL (`configs/meshes/SmTIASv3.stl`) から抽出して `scene_baseline.yaml` を更新．`scripts/extract_led_positions_from_stl.py` で連結成分分割→ LED/カバー識別→ bottom/right/left 自動命名．主な変更: 下基板 LED 配置を「等間隔 8.7mm」→「3+ギャップ+3 (4.2mm+10.8mm+4.2mm)」へ訂正（実機写真の中央電流制限抵抗 2 個と整合）．左右基板も実位置に修正．**形状指標は ~1% 以内のほぼ不変**（多重反射が支配的，LED 数 mm 誤差は ROI 上で平滑化）．絶対 mean は +10% 増加（α 値 0.962→0.873）．既知差分 #2 をクローズ．TEST_03 比較パネルに Step 8-9 を追加（5 枚並列）． +- **LED 基板カバーを 3 枚構成に展開**: 従来は下基板用 `LED基板カバー.stl` 1 枚のみだったが，`scripts/extract_led_positions_from_stl.py --export-covers configs/meshes/` で SmTIASv3.stl から `LED基板カバー下/右/左.stl` の 3 ファイルを書き出し，`scene_baseline.yaml` の geometry を `led_cover_bottom/right/left` の 3 メッシュエントリに展開．右・左基板の LED が「カバーなしで浮く」状態を解消．多重反射計算への影響は軽微だが物理的に正確． +- **Step 8-10 完了**: LED 配光を `spot` emitter (cutoff=90°/beam=30°，FWHM 120° 一致，flux 保存 I_0=0.026784 W/sr) で表現する試行．`SpotLight` クラスを `schema.py` に追加，`lights.py` に spot 分岐実装，`configs/scene_baseline_spot.yaml` を並列保持．**目視で X 方向の対称性が部分改善**（下端の明るい領域が中央寄りに集中）だが，数値指標は微悪化（CoV +4%, 勾配 +15%）．LED 指向性は形の一部（X 方向）を変えるが，Y 方向の中央ピークは LSC モデル化（Step 8-N）が必要．本格採用は LSC との組み合わせ評価後に判断．付随発見: spot で mean が 14.6× 暗くなる（理由は spot falloff 関数の cos vs 角度ドメイン smoothstep の解釈差等を仮説）． +- **Step 8-11 完了**: データシート LP-2835D90VW 準拠の照明モデルを統合．`configs/scene_baseline_datasheet.yaml` に並列保持．spot を cos^1.2 相当の前方凸 (cutoff=85°/beam=26.72°，FWHM 111.72°) に詳細化 + 反射率を Step 8-6 で導出した物理整合点 0.89 に変更 + I_0 を規格値 Φv=17.5 lm から導出 (I_0=0.021951 W/sr)．**形は依然 Y 軸単調勾配**で Step 8-10 と Step 8-9 の中間値．**データシート従順度を上げても形は実機に近づかない**ことを確定．副次的に「規格値だけで mean を実機に合わせることはできず，校正値には他のレバーの累積吸収が含まれる」が再確認された．本筋 LSC モデル化が依然必要． +- **Step 8-12 完了**: Helmholtz 相反原理を Mitsuba 上で実証検証．`schema.py` の RenderConfig に `ptracer` integrator を追加，`configs/scene_baseline_perspective_{path,ptracer}.yaml` で perspective sensor + scalar_rgb + spp=4096 で比較．**bot/top 比が path 2.035 vs ptracer 2.006 で誤差 1.4% で一致**＝形は方向独立．絶対値は Mitsuba 実装の正規化差で 1.99× 違うが形（空間パターン）は同じ．副次的発見: **orthographic + ptracer は Mitsuba 3 では実行不能**（`Endpoint::sample_direction()` 未実装）．これにより「方向変更で形を実機に近づける道は無い」が確定し，**LSC モデル化が唯一の道**である結論が強化された． + - 次のアクション（キャリブ再開時，当時の方針）: 残差に **LSC（ISP レンズシェーディング）順方向モデル**を当てる（物理動機づけ低自由度形、overfitting 回避・取得パラメータ数明記）．※後の Step 8-13 で本方針は不採用に確定（下記）． +- **速度最適化ワーク開始**（キャリブ作業を一旦中断）: [TEST_04 シミュレーション速度最適化履歴](06_TEST/TEST_04_シミュレーション速度最適化履歴.md) に試行を集約．**Speed-0 ベースライン計測完了**（`configs/scene_baseline.yaml`，3 回中央値）: **B1 sm-render = 507.86 s（≈8.46 分）/ B2 sm-visualize path bake (samples=16) = 55.97 s**．**副次発見**: `DRJIT_LIBLLVM_PATH` 環境変数の消失で sm-render が ImportError でクラッシュしていたことを発見．`C:\Program Files\LLVM\bin\LLVM-C.dll` を発見し **User scope に永続化**して復旧．sm-visualize の direct bake は内部 scalar_rgb 固定のため過去ログでも警告は出ていたが完走していた．**方向修正**: Speed-1 当初の「JIT 有効化で高速化」は既に JIT 経路に乗っているため不成立 → 「LLVM-C.dll 自動検出と診断ログ」に再定義（再発防止）．**本命の高速化レバーは Speed-2 path bake wavefront 化**（10× 以上見込み）．GPU は Intel HD Graphics 520 のみで CUDA 不可，CPU 側完結方針．精度（spp/max_depth）は不変． +- **Speed-1 完了**: `src/sm_tias_lightsim/runtime/llvm_init.py` に `ensure_drjit_libllvm_path()`（標準パス自動探索→ `os.environ` 設定）と `log_variant_status()`（llvm_/cuda_/scalar_ 経路を INFO 明示，要求 llvm_* で実 scalar_* なら WARNING 追加）を新規実装．`render/runner.py` で variant=llvm_* 時に自動検出を呼び、`ImportError` 時は原因明示ログ→ re-raise．`visualize/baker.py` でも `log_variant_status` 呼び出し追加＋ Speed-2 wavefront 化用に LLVM 自動探索の分岐を先取り．`cli/render.py` で import 順を制御．`docs/02_ENV/ENV_02_環境構築手順.md` に LLVM インストール手順・DRJIT_LIBLLVM_PATH 説明・動作確認コマンドを追記．**速度は不変**（コード経路同等）．数値同等性: SHA256 は MC 内部シードで異なるが平均相対誤差 7.23e-05 で統計同等性パス．これで「環境変数が消えて沈黙クラッシュ」する事故が再発しない土台が整備された． +- **速度最適化ワーク一旦中断**（Speed-2 path bake wavefront 化は未着手）: **実時間の改善は実質ゼロ**（B1=508s／B2=56s で不変）．副次的成果として環境破綻問題の発見と恒久対処，JIT 診断ログ，ベンチ条件のドキュメント，テスト追加が得られた．中断理由: B2 は現状ボトルネックではなく，B1 は CPU 完結・精度据置の制約下で取れる打ち手が限定的．本筋のキャリブ作業（LSC モデル化）に戻ることがプロジェクト目的により近い．再開条件: path bake samples を増やすユースケース発生／NVIDIA GPU 利用可／クラウド計算活用判断／キャリブ反復回数増加でバッチ時間が研究進度を圧迫した場合．詳細・Speed-2 テンプレ保持は [TEST_04 中断記録](06_TEST/TEST_04_シミュレーション速度最適化履歴.md#中断記録-suspension-note--2026-05-28) 参照． +- **キャリブ方針の根本見直し（2026-05-28）**: 「シミュ vs 実機 PNG の比較」を再検討した結果，**実機 PNG 自体が定量データとして揺らいでいる**ことが判明．MiniTIAS の現行撮影は AE/AWB/NR/EDGE/TONEMAP/SHADING がすべて Camera2 API のオート/デフォルトで，撮影ごとに露光・WB・補正量が変動する．既存 baseline `MiniTIAS_20260408_144434` もこのモードで取得されており，シミュ側でいくらモデルを精緻化しても比較対象が不安定．**当初考えていた「LSC モデル化」より上位の問題**として「**定量撮影モード**」を MiniTIAS 側に追加することを優先する．Android Camera2 API には `STATISTICS_LENS_SHADING_CORRECTION_MAP`・`SHADING_MODE=OFF`・`MANUAL_SENSOR`/`MANUAL_POST_PROCESSING` 能力フラグが存在し，これらを活用すれば「ISP 介入を最小化した再現性ある撮影」が可能．要求仕様を [TECH_01](05_TECH/TECH_01_定量撮影モード要求仕様.md) に，ハンドオフ手順を [TECH_02](05_TECH/TECH_02_MiniTIAS引き継ぎ手順.md) に新規作成．データ受け渡しは `reference_measurement/quantitative/` 配下（gitignore 対象）．SmTIAS-LightSim 側のキャリブ作業は本仕様書を MiniTIAS に渡した時点で一旦停止． +- **MiniTIAS 側で定量モード実装完了（2026-06-01）**: [TECH_03](05_TECH/TECH_03_定量モード実装報告とSHADING_MODE相談.md) と [TECH_04](05_TECH/TECH_04_MiniTIASへの回答.md) を取り込み．**AQUOS sense3 (SH-02M) は `LEVEL_3`（最上位）でハードウェア能力フル**．Phase 1〜5 全完了で **DNG (RAW_SENSOR) 経路を第 1 優先採用**．撮影設定: 1/60s + ISO 40 + AWB/NR/EDGE/AF/AE OFF + TONEMAP 線形 + BLACK_LEVEL_LOCK + SHADING_MODE=HIGH_QUALITY (★) + STATISTICS_LENS_SHADING_MAP_MODE=ON．LSC マップは 13×17．保存ファイルは `MiniTIAS_QM_*.{dng, meta.json, preview.jpg}` 3 種．**SHADING_MODE 判断**: HIGH_QUALITY を本流維持（Mitsuba orthographic 出力 ≒「ISP が完璧に補正できた場合の理想値」で HIGH_QUALITY DNG と直接比較が物理整合）．OFF 切替は将来のフォールバック条件 C1-C3 発動時のみ．データ転送は **adb pull 推奨**．既存実機 PNG の Y' 抽出は BT.601 係数（Rec.709 ではない）も判明． +- **作業フェーズを A/B に分割（2026-06-01）**: 「連射再現性が確保できてもシミュとの対応が取れなければ意味が薄い」という研究上の判断から，**フェーズ A: 1 ショット撮影でシミュ vs 実機対応を先に検証** → **フェーズ B: 対応が取れたら連射 V1 再現性検証**の二段階方式に変更．フェーズ A で MiniTIAS 側に依頼するのは **画素統計・Hot pixel map（高優先 2 件）と白板 1 ショット試し撮りのみ**．**連射 UI は高優先→フェーズ B に降格**．SmTIAS-LightSim 側は DNG/meta.json/LSC マップ読み込み I/F・新規 baseline config を実装し，1 ショット突合で既存通常モード baseline 残差 2.1× が定量モードで変化するかを観察．[TEST_01](06_TEST/TEST_01_キャリブレーション検証履歴.md) に **Step 8-13** として記録． +- **DNG 対応を MiniTias-Evaluation 側にも依頼（2026-06-01）**: PNG から DNG への撮影フォーマット変更に伴い，MiniTias-Evaluation も実機データの一次窓口として DNG 読み込み I/F の追加が必要．既存パターン（`uniformity.py` を MiniTias-Evaluation から SmTIAS-LightSim にコピー）を踏襲する役割分担を採用：**MiniTias-Evaluation 側で正規実装 → SmTIAS-LightSim 側にコピー**．[TECH_05](05_TECH/TECH_05_MiniTiasEvaluation_DNG対応要求仕様.md) に要求書を作成．既存 PNG 経路と並列対応（後方互換）．依存追加: `rawpy>=0.21.0`． +- **MiniTias-Evaluation 側 Phase 1 完了とハンドオフ受領（2026-06-01）**: TECH_05 Phase 1 (DNG 読み込み I/F) と LSC 順適用プロトタイプ・新指標 (動径 min/max 比) が完成．受領記録は [TECH_06](05_TECH/TECH_06_MiniTias-Evaluation引き継ぎ受領.md)，関連分析は [TEST_05](06_TEST/TEST_05_PNG_DNG評価比較.md) と [TEST_06](06_TEST/TEST_06_外乱光影響評価.md)．**5 つの重要発見**: (1) **TECH_05 の `apply_lsc_inverse` は誤り**（DNG は LSC 未補正で逆ではなく順方向適用が正しい．TECH_05 §4 を訂正済）．(2) **過去 Step 8 キャリブの残差 2.1× はドメイン不一致**：正しい linear 比較では DNG linear+LSC 0.0689 vs シミュ linear 0.183 = **真の残差 2.66×**．(3) **新実機ターゲット = `MiniTIAS_QM_20260601_124500`（暗闇撮影）**: CoV=0.0695, 勾配=8.35%, 中心/周辺=1.0911, 動径 min/max=0.860．Step 8-13 以降の正規 baseline．(4) **外乱光ロバスト確認**: 室内灯 ON/OFF で指標差 < 1%．SmTIAS 自前照明が支配的で外乱光モデル化不要．(5) **新指標 `calc_radial_min_max_ratio`** を追加． +- **S2 完了 (2026-06-01)**: `src/sm_tias_lightsim/evaluation/dng_loader.py` を `handoff_smtias_lightsim/src/dng_loader.py` の完全コピーで新規作成．`radial.py` に `calc_radial_min_max_ratio` をマージ追加 (nan ビン除外を移植時に補強)．`pyproject.toml` に `rawpy>=0.21.0` 追加 (実 rawpy==0.27.0)．**検証 V4 が完全一致**: 実 DNG を読み込んで LSC 順方向適用 + 白板 ROI で評価指標 6 件が相対誤差 < 1e-6 で期待値完全一致，空間指標 3 件も絶対誤差 < 0.003．Refactorer 判断: `dng_loader.py` 内部の `_apply_srgb_oetf` は既存 `oetf.py:apply_srgb_oetf` と実装重複だが「コピー方針優先」「用途が異なる」「違反基準未満」でそのまま放置． +- **S3 方針見直しと Step D 完了 (2026-06-01)**: ユーザー指摘により「sm-evaluate に DNG 入力経路を追加する」当初案は **不採用**（実機 DNG 評価は MiniTias-Evaluation の本業で完結，重複実装不要）．S3 を **3 項目に絞り込み**: Step D (動径 min/max 比を sm-evaluate に統合)・Step C' (新規シミュ用 baseline config)・Step G (シミュ再評価 → Step 8-13 記録)．**Step D 完了**: `MetricsConfig.radial_min_max` をスキーマ追加，`cli/evaluate.py` で `_run_radial_min_max` を追加して metrics.csv に 4 列追加，コンソールサマリに 2 行追加．`radial_profile` を再利用（重複算出回避）．後方互換維持．SPEC_04 §動径 min/max 比 を追記． +- **Step C' 完了と Step G 計測 (2026-06-02)**: `configs/eval_baseline_dng_target.yaml` を新規作成（eval_baseline_linear.yaml ベース，target_mean=207.82，radial_min_max=true，OETF なし）．Step 8-13 数値: シミュ CoV=0.1826, 勾配=24.65%, 中心/周辺=1.3271, 動径 min/max=0.6151．実機 DNG+LSC (CoV=0.0695, 勾配=8.35%, C/P=1.0911, 動径 min/max=0.860) と比較して **残差 2.63×**（TECH_06 予想「真の残差 2.66×」とほぼ一致）．過去 Step 8-3 の「2.1×」は PNG sRGB ガンマ圧縮による楽観値．**LSC 取り扱いの結論を [TECH_07](05_TECH/TECH_07_LSC取り扱い方針.md) に一元化**: 3 プロジェクト役割分担 (MiniTias=HIGH_QUALITY 撮影 / MiniTias-Evaluation=lscMap 順方向適用 / SmTIAS-LightSim=一切扱わない)，シミュ側で LSC を扱わない物理的根拠 (Mitsuba orthographic = LSC 完璧補正後相当)，代替案 3 つ全却下，フォールバック条件 C1-C3，残差解釈 を明文化． +- **実機変更とシミュ側対応の整合マッピングを明文化 (2026-06-02)**: [TECH_08](05_TECH/TECH_08_実機変更とシミュ側対応.md) として作成．実機側 8 項目変更に対するシミュ側 3 層 (Mitsuba シーン定義 α / sm-render β / sm-evaluate γ) の対応をマッピング．**結論: シミュ側で実際に対応が必要だったのは sm-evaluate の config レベルでの OETF 無効化 (#4) と mean アンカー調整 (#3) の 2 項目のみで，他はすべて対応不要 (Mitsuba は per-channel 独立計算で AWB/AE/NR/EDGE 概念なし，orthographic で LSC 自然対応)**．計 15 項目以上で網羅チェック．**残差 2.63× は ISP 関連の対応漏れではなく，シミュ物理モデル誤差 (反射率精度・LED 配光モデル・メッシュ幾何精度等) が主因**と推定． + - 補足: **「対応不要」を 2 タイプに細分化** (TECH_08 §許容している構造的差異)．**タイプ I (本質構造同一・対応概念なし)** = AWB/NR/EDGE/LSC 等，**タイプ II (構造的差異あり・白板で許容)** = AF (焦点モデル)/絞り口径食/ピクセル積分/センサノイズ/QE 波長依存/シャッター方式/温度依存．特に AF は実機 perspective+固定焦点 vs シミュ orthographic 無限遠相当という構造的違い．白板撮影では影響軽微で許容．舌模型評価時や残差精緻化フェーズで再評価対象． +- **S3 全体完結 — TEST_01 に Step 8-13 正式記録 + handoff 整理 (2026-06-02)**: [TEST_01 §Step 8-13](06_TEST/TEST_01_キャリブレーション検証履歴.md) に新方針 (実機 DNG+LSC linear) でのシミュ突合を正式記録．俯瞰サマリ表に新ターゲット (CoV=0.0695) と Step 8-13 結果 (CoV=0.1826, 残差 2.63×) を追加．§Step 8-N 候補 (LSC 順方向モデル) を「不採用 — Step 8-13 で方針確定」に更新（歴史的記録として保持）．`handoff_smtias_lightsim/` は整理: 参考スクリプト `run_uniformity_dng.py` のみ `reference_measurement/quantitative/reference_scripts/` に移動，他は取り込み済みのため削除． +- **LED データシート調査結果を [TECH_09](05_TECH/TECH_09_LEDデータシート調査結果.md) として明文化 (2026-06-02)**: **OEM 元 HONGLITRONIC (広州，鸿利智汇集团) のデータシートが存在**することが判明．LED Paradise LP-2835D90VW は HONGLITRONIC HL-A-2835D90VW シリーズ (PDF: lcsc.com/datasheet/C5362368.pdf) の OEM 再販品．**配光図から数値読み取り: ほぼ厳密 Lambertian (cos θ) と一致** (0°→1.0, 30°→0.87, 60°→0.50, 80°→0.15, 90°→0)．**重要な含意**: (1) 現状の area light Lambertian モデルはデータシート実測と整合．配光モデル精緻化余地は限定的．(2) **過去 Step 8-11「データシート従順版」(cos^1.2) は実態はデータシート不整合**だった (同等品の典型配光を借用)．道理で形状指標が悪化．(3) **Step 8-14 候補 B (LED 配光詳細化) の意義は限定的**．SPEC_03 の「やや前方凸」記述は訂正対象．取得 PDF は REFERENCE/datasheets/ に配置 (gitignore 対象)． +- **docs/05_TECH と docs/06_TEST に README 追加 (2026-06-02)**: 15 ファイルがフラットに並んで散らかり感があるため，性質分類と navigation を README で提供．05_TECH/README: 🟢 現状方針 (TECH_07-09) と 🔵 議論の経緯 (TECH_01-06)．06_TEST/README: 🟡 中核 (TEST_01-03) と 🔵 クローズ済み (TEST_04) と 📋 外部スナップショット (TEST_05/06)．ファイル削除・移動はせずナビゲーションのみ追加． +- **残差 2.63× の主因候補を [TECH_10](05_TECH/TECH_10_残差主因候補の網羅整理.md) として網羅整理 (2026-06-02)**: Step 8-14 候補選定の判断材料．5 カテゴリ 18 項目を網羅．当初の優先度評価: 🥇 A1 内壁の非 Lambertian 性 / 🥈 A8 反射率 R=0.85→0.89 / 🥉 A9 max_depth 8→16+．（※その後の検証で優先度は更新．下記参照） +- **Step 8-14 候補 γ (D1 ROI 整合の再確認) 完了 — クリア (2026-06-02)**: 設定変更ゼロ，既存設定の数値検証のみ．シミュ ROI (24, 37, 464, 450) の物理範囲 (幅 90.63×91.41 mm) と実機 ROI (539, 1015, 1400, 1409) の物理範囲 (物理分解能 0.0654 mm/px → 幅 91.54×92.13 mm) を比較した結果，**物理サイズ差 < 1%・中心位置差 < 1 mm で整合**．3 列パネル `output/_slide_panels/roi_alignment_check.png` でも視覚確認．**残差 2.63× の主因は ROI 整合ではない**ことが確定．副次発見: 評価板は実機画像中央から下方向に約 4.2 mm (65 px) オフセット配置だが ROI もそのオフセットに沿って選択されているため物理領域として整合． +- **Step 8-14 候補 β (A1 内壁の非 Lambertian 性) 完了 — クリア (2026-06-02)**: 候補 🥇 1 位だった A1 を 3×3 グリッド感度分析で検証．スキーマ拡張 (`BlendBSDFConfig` + `RoughConductorBSDFConfig`，`MaterialConfig` Union 拡張，forward reference + `model_rebuild()`) と `materials.py` 再帰変換 (`_build_bsdf_dict`) を新規実装．テンプレ `configs/scene_baseline_blend.yaml` + `scripts/sweep_blend_bsdf.py` + `scripts/build_blend_bsdf_panel.py`．**weight ∈ {0.05, 0.15, 0.30} × α ∈ {0.1, 0.3, 0.6} の 9 ジョブ実走 (75.5 分)**．結果: ベースライン純 diffuse (CoV=0.1826) と比較して **全 9 パターンが悪化または不変**．実機 (CoV=0.0695) 方向と **逆方向に動く**．「形」は w=0.30 で下端中央に specular 集中スポット顕在化．物理的解釈: 純 Lambertian は cos 重み散乱で多重反射の均一化作用が最大．specular 成分は光を集中させ均一化を阻害．**3D プリンタ白フィラメントは完全 Lambertian として扱うのが実機挙動に近い近似**と判明．**A1 は残差 2.63× の主因ではない**ことが確定．副次成果: スキーマ層に `blendbsdf` + `roughconductor` のサポートが入り再利用可能． +- **LED グループ別 sanity check 完了 — TEST_07 として報告 (2026-06-03)**: 「シミュが下/右/左の 3 LED 基板を物理位置どおりに独立にモデル化できているか」の基礎健全性確認．`scripts/sanity_led_groups.py` で各基板の 6 LED だけを ON にした一時 YAML を生成 → 3 ジョブ sm-render (約 25 分) → 比較パネル．結果: **方向性 ✓** (bottom は下端中央/right は右側面寄り/left は左側面寄り)，**左右対称性 ✓** (right mean=47.10 vs left mean=47.08)，**量的バランスは bottom が right/left の 2.10× で強い**．物理的説明: bottom LED は評価板下端真下に X 中央寄り集中で直接光が広範囲 / right/left LED は側面外側 Y 中央付近に分散で中央は多重反射経由．**線形性検証は別途未実施**（既存 `output/baseline/luminance.npy` が Step 8-1 時点の古いもの．Mitsuba は理論線形なので baseline 再生成で一致見込み）．副次発見: 実機の right/left は **完全な左右対称設計ではない**（Fusion STL 実位置と整合）．[TEST_07](06_TEST/TEST_07_LEDグループ別動作確認.md) 参照． +- **scene_baseline.yaml の max_depth を 8 → 16 へ更新 (2026-06-03)**: Step 8-14 候補 α 前半の結論「d=16 が実用収束点」を反映．SPEC_03 既知差分 #6 (未対処の max_depth=8) を解消．SPEC_03 の関連 4 箇所を一括更新．影響: 今後の sm-render は自動的に d=16 で実行され理論累積 92.6% を取り込む．計算時間は約 2× (8.5 分 → 17 分) に増加するが形状指標 4 つすべてが d=8 時代より実機方向に改善 (CoV 0.1817 → 0.1604, 勾配 24.01% → 20.59%)． +- **Step 8-14 候補 ξ (A2/A3 LED 配光 cutoff スイープ) 完了 — 配光が形改善の本物の候補として初実証 (2026-06-03)**: ユーザー要請「配光条件を変えてどのような変化が起こるかの実験（データシートに合わせる必要なし）」に基づき，`scripts/sweep_led_distribution.py` で spot emitter の cutoff_angle を {30°, 60°, 90°, 120°, 150°} で 5 値スイープ (beam_width = cutoff/3，max_depth=16，約 85 分)．**重要な 2 つの発見**: ① **「area light → spot」のステップが本質的** — area (Lambertian) の angular_ratio=0.4536 → spot (どの cutoff でも) 0.34〜0.36 へ **25% 大幅低下** (実機方向)．② **cutoff スイープ内 (30°→150°) では effect 限定的** — angular_ratio は +0.018 のみ．**A8 と真逆のパターン**: 数値悪化 (CoV +3〜11%) するが形改善 (angular_ratio -25%)．「数値の偽物の一致」(A8) と対をなす「形改善の本物の候補」初実証．物理的解釈: spot は +Z 方向にしか光を出さない → 内壁に当たる成分減・直接光増 → LED 直下の明点 → 半径方向ばらつき支配 (angular_ratio 減)．area は半球全方向拡散で多重反射 ambient 支配 → Y 軸勾配．副次発見: 数値最良点 (cutoff=90°) と形最良点 (cutoff=30°) が異なる→キャリブの優先順位議論を明確化．**TECH_10 優先順位を再更新**: A2/A3/ξ を「形改善候補」へ昇格． +- **Step 8-14 候補 α 後半 (A8 反射率スイープ) 完了 — 数値改善のみ・形は逆効果 / 「数値の偽物の一致」の初の定量実証 (2026-06-03)**: `scripts/sweep_reflectance.py` で d=16 新基準のもと R ∈ {0.75, 0.80, 0.85, 0.89, 0.92} を 5 値スイープ．新指標 (shape_metrics) を初めて感度分析に投入．結果: 既存 4 指標 (CoV/勾配/C/P/動径 min/max) は単調改善 (R=0.75→0.92 で CoV 0.186→0.142 で残差 24% 縮小) するが，**新指標 angular_ratio は 0.408→0.494 で実機方向と逆に増加**．実機は中央ピーク楕円 (同心円的) なので **形は実機から遠ざかる**．物理的解釈: R 上昇で ambient 増 → 半径方向の偏りは圧縮されるが角度方向ばらつきは相対的に圧縮されにくい → angular_ratio 増加．**形改善の本筋は B1 筐体幾何精度に最終確定**（A1/A8/A9 すべてクリア済で構造的再配分系のみ残る）．副次発見: R=0.85 の CoV=0.1604 が max_depth スイープ d=16 と完全一致．新指標を導入していなければ気づけない発見で，形状指標見直し (TECH_11) の正当性が定量データで裏付けられた． +- **Step 8-14 候補 α 前半 (A9 max_depth スイープ) 完了 — 数値改善のみクリア・形不変 (2026-06-03)**: ユーザー仮説「現状 d=8 では 0.85^8≈0.27 で取りこぼし大」を 5 値スイープ {8, 12, 16, 20, 28} で検証 (`scripts/sweep_max_depth.py` 約 85 分 + `scripts/build_max_depth_panel.py`)．結果: 全 4 形状指標が **単調に実機方向に改善** (d=8→28 で CoV 0.1817→0.1583 で残差 20.9% 縮小)．mean は 207.82 で固定．**実用的な収束は d=16 で達成** (d=16→28 で CoV 1.3% のみ)．**「形」は完全に不変** (Y 軸単調勾配のまま contrast が緩むだけ)．物理的解釈: 多重反射は **空間的に均一な ambient 成分**で，足しても暗/明の絶対差は縮むが空間配置は不変．「LED が下にしかない」配置の非対称性は除去不能．**ユーザー仮説の評価**: 方向性は正しい (21-28% 残差縮小) だが実用収束は d=16，実機 (CoV=0.0695) には届かず残差は形改善で詰める必要．新キャリブベースライン: **d=16**． +- **形状指標の本質的見直しと新指標導入 (2026-06-03)**: 「数値が実機方向に動いても形は変わらない」が続けて確定したため，ユーザー指摘「現状 4 指標は不均一性の絶対量しか測れず，Y 軸単調勾配と中央ピーク楕円を構造的に区別できない」に対応する **形を直接評価する 5 指標** を追加実装．`src/sm_tias_lightsim/evaluation/shape_metrics.py` (新規): `calc_intensity_centroid` / `calc_angular_radial_decomposition` (angular_ratio: 0=同心円, 1=方向依存) / `calc_ssim` (scikit-image 依存) / `calc_ncc` / `calc_intensity_pca` の純関数 5 つ．`MetricsConfig` に `shape_metrics` / `shape_reference` を追加（後方互換）．`configs/eval_baseline_dng_target_shape.yaml` を新規作成．`pyproject.toml` に `scikit-image>=0.21.0` を追加．[TECH_11](05_TECH/TECH_11_形状指標の見直しと新指標導入.md) で背景・計算式・予想値・遡及的注記を記録．今後の評価方針: **数値指標 4 + 形指標 5 + 視覚比較の 3 軸評価**で「数値改善のみで形が変わらない候補」と「形を変えうる候補」を明確に区別する．