refactor: add Japanese domain comments for investigation flow maintainability

[sasazaki1994]

Motivation

• 保守性と将来のAIエージェント作業を容易にするため、主要な調査パイプライン箇所にドメイン意図・注意点を日本語で補足しました。
• 実装意図（run status 遷移、キャッシュ条件、ソース検証方針、Unknown/Lineage の派生意図など）を明確にして誤解を防ぎたい為です。
• 挙動・型・スキーマ・APIには一切手を入れず、コメントのみで説明性を高めることを目的としています。

Description

• サーバー側分析フローに日本語コメントを追加し、create-analysis-run-from-providerではrun status遷移、手動URL時のrun cache回避、プロバイダ例外の安全なメッセージ化の意図を説明しました.
• 永続化ロジック(persist-generated-answer-graph)にてソース検証はbest-effortである旨、プロバイダの仮ID(__src_n__)を永続化後IDへ置換する理由、legacyなclaim->source参照の互換処理の意図を追記しました.
• ソース取込処理(source-intake-service)にてdiscoveryの補助役割、manual/topic/discoveryの結合順序、normalized URLによる重複除去方針を明記しました.
• UI/feature層ではbuild-unknownsとbuild-source-lineageにて各ビューが派生ビューである意図を説明し、RunResultViewには調査導線（Mission → Evidence → Unknown → Lineage → Report）と選択状態連動の目的を追記しました.
• そのほか、create-run / share/[token] / 型定義(GeneratedAnswerGraphPayload) / テスト（source-intake.test.ts）に必要最小限の意図コメントを追加しました.
• 変更点はコメントのみであり、動作・型・DB・プロバイダスキーマ・テスト期待値は一切変更していません.

Testing

• 実行したコマンド: pnpm lint, pnpm typecheck, pnpm test, pnpm build, pnpm test:e2e（環境依存）.
• pnpm lint は成功しました.
• 型チェック (pnpm typecheck) は成功しました.
• ユニット/統合テスト (pnpm test) は成功しました（45 files, 206 tests 全てパス）。
• ビルド (pnpm build) は成功しました（Next.js のプロダクションビルド通過）。
• E2E (pnpm test:e2e) はこの実行環境でPlaywrightのブラウザ実行ファイルが未インストールであるため失敗/ブロックとなり、環境依存のため pnpm exec playwright install を実行できる環境で再実行を推奨します.

---

Codex Task

Summary by CodeRabbit

リリースノート

• Chores
  • 内部コメント追加により、実装方針と処理フローの可視化を改善しました。

---

注記: このリリースに含まれるのは内部ドキュメンテーションの改善であり、ユーザーに対する機能や動作の変更はありません。

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 27372a45-2a04-4384-8701-74ed825169e5

📥 Commits

Reviewing files that changed from the base of the PR and between d8fcdce and 27b5809.

📒 Files selected for processing (10)

• src/app/actions/create-run.ts
• src/app/share/[token]/page.tsx
• src/features/run/components/run-result-view.tsx
• src/features/run/lib/build-source-lineage.ts
• src/features/run/lib/build-unknowns.ts
• src/server/analysis/create-analysis-run-from-provider.ts
• src/server/analysis/persist-generated-answer-graph.ts
• src/server/analysis/source-intake/source-intake-service.ts
• src/types/answer-graph-generation.ts
• tests/source-intake.test.ts

---

Walkthrough

このPRは、TraceMapシステムの複数のコンポーネント中に説明的なコメントを追加します。実装ロジックや公開APIの変更なしに、run作成権限、共有アクセス制御、ビュー構築、パイプライン処理の設計制約と動作を文書化しています。

Changes

システムアーキテクチャと処理フロー説明

Layer / File(s)	Summary
Run作成と権限管理 src/app/actions/create-run.ts	フォーム入力フィールド名questionのUI互換性、および未認証アクセス防止とowner scopeによる権限分離の方針を説明するコメント
共有ページアクセス制御と安全性 src/app/share/[token]/page.tsx	トークンベースの限定公開、SEO露出防止のnoindex/nofollow強制、および共有閲覧者の再実行不可による安全な失敗表示を説明するコメント
実行結果表示とビュー統合 src/features/run/components/run-result-view.tsx	TraceMapの固定表示順（Mission→Evidence→Unknown→Lineage→Report）およびグラフ・クレーム・ソース詳細パネル間の同期選択挙動を説明するコメント
出典系譜と不明点マップ構築 src/features/run/lib/build-source-lineage.ts, src/features/run/lib/build-unknowns.ts	Source Lineage Liteを既存スナップショットから推定する軽量ビュー、Unknown Mapをclaim/alert/source-qualityから派生するビューとして位置づけ、重複排除をcategory+関連ID+reasonで集約する方針を説明するコメント
分析実行作成とキャッシュ再利用 src/server/analysis/create-analysis-run-from-provider.ts	手動URL指定時の優先方針、MVP v2の同期実行ステータス遷移（queued→processing→completed/failed）、同一topic+provider+modeでのキャッシュ再利用条件、provider例外の安全文言変換を説明するコメント
応答グラフ永続化と正規化 src/server/analysis/persist-generated-answer-graph.ts	ソース検証のbest-effort取り扱い、仮IDから永続化後の実IDへの正規化、legacy配列の直接サポート変換とsupports優先を説明するコメント
ソース取り込みと重複排除 src/server/analysis/source-intake/source-intake-service.ts	ソースディスカバリー失敗時も実行継続・理由をignoredUrlsに保持、manual/topic/discovery候補を同一パイプライン処理、normalizedUrlベースの重複排除で追跡パラメータ差分を吸収することを説明するコメント
型定義とテスト仕様 src/types/answer-graph-generation.ts, tests/source-intake.test.ts	GeneratedAnswerGraphPayloadを永続化中間format、graphJsonを描画スナップショットと位置づけ、ソース取り込みテストの入口仕様（抽出→正規化→安全判定）を説明するコメント

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• sasazaki1994/TraceMap#29: run-result-view.tsx での表示順（Mission→Evidence→Unknown→Lineage→Report）コメント追加と同じUI順序・ガイド領域で整合するため。
• sasazaki1994/TraceMap#38: create-run.ts / source-intake-service.ts の手動ソースURL intake前提・優先方針コメント追加が同一箇所の実装変更と対応しているため。
• sasazaki1994/TraceMap#32: build-source-lineage.ts での Source Lineage Liteアプローチのドキュメント化が、lineage-view実装の変更と同じコードパスに接しているため。

Poem

🐰 コメントが静かに添えられて
設計意図の光が灯る
ロジックは同じ、意思は鮮明
次の開発者への地図となり
システムの心臓の鼓動を映す ✨

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/add-japanese-comments-for-code-clarity

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}