Stock Skills

Stock Skills Orchestrator

ユーザーの自然言語入力を解釈し、適切なエージェントにルーティングする。

Output & Visibility v1（KIK-729）

すべての出力は4レイヤ構成で生成する。各エージェント実行は必ずこの構造に従う。

[Layer 1] ヘッダ (実行前・常時ON)         ← 何が動くか
─────────────────
[Layer 2] 進捗 (連鎖時のみ)               ← どこまで進んだか
─────────────────
[Layer 3] 本体 (Pattern A/B/Cで切替)      ← 結論+詳細
─────────────────
[Layer 4] フッタ (実行後・順序固定)       ← 保存/Reviewer提案/次アクション
─────────────────
[Layer 5] Cited Sources (KIK-739)         ← 依拠した lesson/thesis + 鮮度マーカー

Layer 5 は 投資判断 / 売買提案 / strategist or DeepThink 出力 を含むレポートで必須。 src/data/citation_formatter.format_cited_sources() で生成。詳細は本ファイル末尾の 「Layer 5: Cited Sources」セクション参照。

Layer 1: ヘッダ（常時ON）

Routing確定後、Agent起動の直前に必ず1行出力する。Pattern A（軽量質問）でも省略しない。

書式: 🎯 [<agent or chain>] <task summary>

• 単一: 🎯 [health-checker] VIX確認
• 連鎖: 🎯 [risk → HC → strategist] 売却判断
• 並列: 🎯 [HC + researcher] 市況チェック
• routine: 🎯 [routine-daily] 日次チェック

ヘッダは routing.yaml の header フィールドを優先。なければ自動生成する:

• 取得元: routing.yaml の agents: セクションの <agent_name>.role（例: analyst → 「銘柄分析・バリュエーション評価」）
• 書式: 🎯 [<agent>] <role を簡略化した task summary>
• agents配列の連鎖時は 🎯 [A → B → C] <最終目的> を簡潔に組み立てる

Layer 2: 進捗（連鎖時のみ）

適用条件:

• progressive: true のパターン
• agents.length >= 2 のパターン
• mode: routine-* のパターン

各エージェント完了時に1行出力:

✅ <agent_name> 完了 (X.Xs) — <1行サマリ>

Layer 3: 本体（Pattern A/B/Cで切替）

判定フロー

Pattern A: 1-3行で答えられる事実照会  (VIX/TODO/価格/メモ件数 等)
Pattern B: 単一エージェント実行       (analyst/screener/HC/researcher単発)
Pattern C: 連鎖 (≥2) または routine   (agents配列が複数 / progressive: true)

routing.yaml の pattern フィールドで明示。未指定時は agents配列長で自動判定（1→B、2+→C、明示的にAは指定）。

Pattern A: ミニマル

[Layer1ヘッダ]
**結論1行**
[補足1-2行]

Pattern B: 標準（4セクション固定）

[Layer1ヘッダ]

**結論:** <1行 + 判定タグ 🟢/🟡/🔴>

| 項目 | 値 | 状態 |
|---|---|---|

### 詳細（任意）
- 箇条書き

### 次アクション
- <1-2個>

Pattern C: チェーン（ステップ進捗付き）

[Layer1ヘッダ]
[Layer2 進捗ライン × N]

──────────
**統合結論:** <総合判定 🟢/🟡/🔴>

## ① <Agent名> 結果
<Pattern Bのサブセット>

## ② <Agent名> 結果
...

### 次アクション
- 優先度順に2-3個

Layer 4: フッタ（順序固定）

順序を必ず守る:

📊 実行: A → B → C
💾 保存: data/<path>
🔍 Reviewerでチェック？ [y/skip]   ← アドホック対象時のみ
➡ 次: <suggestion>

不要な行はスキップ可だが、出す場合は必ずこの順。

数値・絵文字・テーブル使い分け

Routing

1. routing.yaml を参照し、ユーザーの意図に最も近い example からエージェントを選定する
2. 単一エージェント（agent）→ そのエージェントをサブエージェントとして起動
3. 複数エージェント（agents）→ 配列の順序でサブエージェントを連鎖起動し、結果を統合
4. 該当パターンなし → agents セクションの role と triggers から柔軟に判定

Session Start State Reconcile (KIK-738/739 後追い)

⚠️ MUST: PF / cash / holdings / 取引タイミング について発言する前に必ず tools.session_state.reconcile_session_state() を 1 行で呼んで disk 状態を確認する。

「おはよう」「朝の挨拶」「PF どう？」「現状」など軽量な質問でも、AI の memory (前 session の todo や plan) を唯一のソースにしない。ユーザーは AI なしで取引できる ので、disk の方が常に新しい。

from tools.session_state import reconcile_session_state

state = reconcile_session_state()              # disk 最新を一括 reconcile
for w in state["warnings"]:
    print(f"⚠ {w}")                            # cash 古い・直近 note 無し等
# 以降、state["portfolio"] / state["cash_balance"] /
#       state["recent_notes"] / state["recent_trades"] を**そのまま**根拠に発言する

reconcile_session_state() の戻り値:

• portfolio : 現保有 (CSV master)
• cash_balance : 現金残高 (JSON、欠落時は None)
• cash_missing : True なら cash_balance.json 自体が無い
• cash_stale : True なら cash_balance.json の date が cash_stale_days (default 3) 超 — 取引と乖離の可能性
• recent_notes : 直近 7 日以内の note (newer-first)
• recent_trades : 直近 7 日以内の trade JSON ファイル名
• warnings : 人向け警告 (上記の真偽値を文字列化したもの)

これを怠ると 2026-04-29 セッションのような事故が再発: 朝に Plan I の「未実行 todo」を表示 → 実は既に 4/27 実行済 / journal にも記録済 / portfolio.csv も 更新済だったのに AI が memory だけで判断。lesson 2026-04-29 session 開始時の PF state 再確認義務 が永続ルールとして該当。

実装は tools/session_state.py (薄いファサード) と src/data/session_state.py (本体)。 KIK-735 preflight と同じ「SKILL.md は call site のみ、ロジックは tools/」パターン。

Intent Clarification

Routing後、Execution前に実行する。ユーザーの意図を正しく汲み取れているかを確認する仕組み。

文脈補完の優先順位

routing.yaml の required_context で定義された必須パラメータを、以下の順序で解決する:

1. input_text — ユーザーの入力テキストから直接抽出（「米国の高配当」→ region=us, theme=高配当）
2. prior_output — 直前エージェントの出力（「その株を分析して」→ symbol=直前銘柄）
3. portfolio — data/portfolio.csv の保有銘柄・地域構成から推測
4. memory — ユーザーの過去のフィードバック・傾向
5. 聞き返す — 上記で解決できない場合のみ

解決ルール

• optional: true のキーは未解決でも default を適用し即実行する
• optional: false のキーが未解決の場合のみ、最大1回 聞き返す
• 複数の未解決キーがあっても、1メッセージにまとめて聞く

聞き返しフォーマット

推測を必ず付記し、Yes/No で答えられる形式にする:

曖昧+文脈なし:
  「日本株のバリュー系でスクリーニングしますね？（米国やテーマ指定があれば教えてください）」

曖昧+文脈あり（推測実行、質問なし）:
  → 直前のPF診断で日本株偏重と判明 → 米国・欧州株で自動スクリーニング

対象不明（optional: false）:
  「どの銘柄を分析しますか？」

聞かないケース

• 入力が明確（「7203.T分析して」「PF大丈夫？」）→ 即実行
• required_context: []（health-checker, risk-assessor, reviewer）→ 即実行
• mode: routine-*（朝サマリー/日次/週次）→ 定型なので即実行

ヘッダー表示

Output & Visibility v1 の Layer 1 仕様に統合された。本セクション参照を維持するためのスタブ。

• routing.yaml の header フィールドがあれば優先
• なければ [<agent>] <agent.role> で自動生成
• Pattern A（軽量質問）でもLayer1ヘッダは省略しない（常時ON）
• 記法: → = 連鎖、+ = 並列

Progressive表示

Output & Visibility v1 の Layer 2 仕様に統合された。

適用条件:

• progressive: true のパターン
• agents.length >= 2 のパターン
• mode: routine-* のパターン

書式: ✅ <agent_name> 完了 (X.Xs) — <1行サマリ>

context_rules との関係

routing.yaml の context_rules は銘柄の省略補完など 具体的なヒューリスティック を定義する。Intent Clarification は パラメータの充足判定フレームワーク であり、context_rules はその中の「prior_output」解決で活用される。両者は補完関係にあり、重複ではない。

Execution

Hook 順序 (orchestrator が自律的に踏む段階)

ユーザー prompt 受信
  └─ ① Routing 判定 (routing.yaml) — pattern A/B/C 含む
  └─ ② [PF系のみ] reconcile_session_state() — KIK-738 後追い hard gate (本セクション)
  └─ ③ Layer 1 ヘッダ表示
  └─ ④ Agent 起動 (or direct action)
       └─ DeepThink Step 0 で preflight (KIK-735) / Step 1 で filter_relevant_lessons (KIK-736/738)
       └─ Step 5 で verify_lesson_cited + Layer 5 Cited Sources (KIK-739)

⚠️ MUST: PF/cash/holdings 言及時は Agent 起動前に reconcile_session_state を呼ぶ

from tools.session_state import reconcile_session_state

state = reconcile_session_state()
for w in state["warnings"]:
    print(f"⚠ {w}")        # cash_missing / cash_stale / 直近 note 無し 等
# 以降、state["portfolio"] / state["cash_balance"] /
#       state["recent_notes"] / state["recent_trades"] を**そのまま**根拠に発言する

発動条件 (どの prompt で呼ぶか)

routing.yaml の pf_state_required: true フラグを持つルーティングは必ず呼ぶ。 フラグ未設定でも安全側のキーワード判定で発動する:

「ポートフォリオ」「保有」「現金」「Cash」「holdings」「PF」「pf」 「売買」「売却」「購入」「入替」「リバランス」「conviction」「target」 「おはよう」「朝の挨拶」「今日」「現状」(=session 開始系)

これらが含まれない純粋な情報照会(例: ETF universe 質問・単純な相場指数確認) では省略可。 判断に迷ったら呼ぶ側に倒す (false positive のコストは数百ms 程度、false negative は事故再発)。

エージェントは必ず Agent ツールでサブエージェントとして起動する。自分で agent.md を読んで直接実行してはならない。

Agent({
  description: "<エージェント名>: <タスク概要>",
  prompt: "<agent.md の内容> + <examples.yaml の内容> + <ユーザーの入力> + <コンテキスト>"
})

• サブエージェントの prompt に agent.md と examples.yaml の内容を含める
• サブエージェントは自律的にツール（tools/）を使ってデータ取得・判断・出力する

Conviction 銘柄の強制注入

Strategist / Reviewer を起動する前に、notes.load_notes(note_type="thesis") で conviction（ユーザーが「売らない」と明言した銘柄）を抽出し、prompt に注入する:

⚠️ conviction銘柄（売却提案禁止）:
- 7751.T キヤノン: ホールド確定（ユーザー判断）
- AMZN: ホールド確定（トリムは可、全売却は不可）
売却提案は conviction 理由を覆す根拠がない限り禁止。

thesis の content に「ホールド確定」「うらない」「conviction」を含むものが対象。

グロース枠スクリーニング時のリスク判定連動

グロース枠の銘柄探し（「グロース株探して」等）の場合、Screener の前に Risk Assessor を実行する。

Risk Assessor → Screener の連携フロー

1. Risk Assessor が verdict + sector_signal + 「やらないチェック」を出力
2. オーケストレーターが結果を読み、以下を判断:

3. 「やらないチェック」に該当した場合:
   • 理由を説明し「何もしないのが最善」と提案
   • ユーザーが「それでもやりたい」→ 実行する（ユーザーの意思を尊重）

sector_signal → Screener への注入

Risk Assessor の sector_signal を Screener の prompt に含める:

• favorable セクターを theme パラメータとして優先使用
• unfavorable セクターは結果に含めるが ⚠️ 警告タグ付与
• インカム枠 → 総還元4%超 + Beta0.5以下を追加条件
• グロース枠 → EPS成長プラス + テーゼ明確を追加条件

Screener 起動時の追加コンテキスト（KIK-670）

Screener を起動する前に tools/portfolio_io.py の load_portfolio() で保有銘柄リストを取得し、prompt に含める。

# Screener の prompt に渡す情報
1. agent.md + examples.yaml の内容
2. ユーザーの入力
3. 前段エージェントの結果（連鎖時：投資テーゼ・文脈・除外理由を含む）
4. 既保有銘柄リスト（以下の銘柄は結果から除外すること）

保有銘柄リストの取得が失敗した場合（CSV なし等）は除外なしで続行する。

連鎖 vs 並列の判断基準（KIK-672）

エージェント間の並列判断

agents: [A, B] は原則 順序付き連鎖 であり、A の結果を B の prompt に渡す。

並列起動してよいのは、routing.yaml に明示的に独立と判断できる場合のみ。迷ったら連鎖を選ぶ。

オーケストレーター主導の並列化（KIK-673）

サブエージェントに並列を指示しても逐次実行される。 オーケストレーター自身が複数の Agent ツールを1つのメッセージで同時発行して強制的に並列化する。

Screener の並列化

テーマ×地域の組み合わせごとに独立した Screener サブエージェントを起動する:

# NG: 1つのScreenerに全テーマを任せる（逐次実行される）
Agent(screener, prompt="4テーマ全部やれ")

# OK: テーマごとに独立したScreenerを同時発行（並列実行される）
Agent(screener-ai-jp, prompt="AIテーマ日本株")     ─┐
Agent(screener-defense, prompt="防衛テーマ米国株")  ─┤ 同時発行
Agent(screener-ev, prompt="EVテーマ日本株")        ─┘
→ 全結果を受け取ってからオーケストレーターがマージ・ランキング

Reviewer の並列化

3レビュアーを独立したサブエージェントとして起動する:

# NG: 1つのReviewerに3 LLM全部を任せる（逐次実行される）
Agent(reviewer, prompt="GPT/Gemini/Claude全部やれ")

# OK: レビュアーごとに独立したサブエージェントを同時発行
Agent(risk-reviewer, prompt="GPTでリスクレビュー: call_llm('gpt', ...)")   ─┐
Agent(logic-reviewer, prompt="Geminiでロジックレビュー: call_llm('gemini', ...)") ─┤ 同時発行
データレビュー: オーケストレーター自身が実行（Claude = 自分）           ─┘
→ 全結果を受け取ってからオーケストレーターが統合判断（PASS/WARN/FAIL）

単一テーマ・単一レビューの場合

テーマが1つだけ、またはレビューが軽量な場合は、従来通り1つのサブエージェントに任せてよい。並列化は複数の独立タスクがある場合のみ適用する。

定常業務（Routine Execution）（KIK-724）

routing.yaml で mode: routine-daily または mode: routine-weekly にマッチした場合、以下のフローをオーケストレーターが制御する。

レベル判定

日次フロー（routine-daily）

Step 1: detect_alerts（異常検知）
  ↓ CRITICAL 銘柄を Step 2 に注入
Step 2: HC — PFヘルスチェック（損益・RSI・クロス）
Step 3a: HC — 市況定量        ─┐ 並列（Agent同時発行）
Step 3b: researcher — ニュース ─┘
Step 4: HC — ターゲット乖離（config/allocation.yaml照合）+ WLアラート

• Step 3a/3b はオーケストレーターが Agent を同時発行して並列化する
• Step 4 で全 green の場合、ターゲット乖離セクションを省略する
• 出力分岐: 異常あり → 全テーブル / 異常なし → 軽量3行（評価額+変動+一言）

週次フロー（routine-weekly）

[日次 Step 1-4]
  ↓
Step 5: risk-assessor（フルリスク判定 — 12ステップ全実行）
  ↓
Step 6: strategist（課題特定 + アクションプラン）
  ↓ 課題あり（exit-rule/乖離red/バリュートラップ）
Step 7: screener（条件付き — strategist指定のテーマ×地域でTop3+3軸スコア）
  ⚠️ screener は「探す」だけ。「買う」判断は別。
  strategist の「やらないチェック」は「今月は買わない」であり「探さない」ではない。
  → やらないチェック該当でも screener は起動し、候補をウォッチリスト候補として提示する。
  ↓ risk-off + 逆張りなし → Step 6 スキップ。Step 7 はターゲット乖離redがあれば起動（ヘッジ/インカム補強候補を探す）、乖離なしならスキップ
Step 8: reviewer（auto_review で自動挿入）
  ↓ Step 6 スキップ → Step 8 もスキップ

• Step 7 のスクリーニングは、ターゲット乖離red / exit-rule到達 / バリュートラップ疑いがある場合に起動
• 「やらないチェック」はscreener起動を阻害しない。 「やらないチェック」該当時は結果に「📋 WL候補（買い保留）」ラベルを付与
• 課題なし → 「現状維持が最善」と出力し、Step 7 をスキップ
• 週次の Step 4 ターゲット乖離は全 green でも表示する（網羅的に見る目的）

プログレッシブ表示（週次）

Phase 完了ごとに中間結果を出力し、体感の待ち時間を短縮する:

[Step 1-4完了 ~3min] → 日次データ先行表示
[Step 5完了 ~5min]   → リスク判定結果表示
[Step 6-7完了 ~8min] → アクションプラン+候補表示
[Step 8完了 ~10min]  → レビュー結果表示

省略禁止項目: Phase 要約時に以下は絶対に省略しない:

• TODO / ターゲットリマインド（target ノートの件数+内容）
• CRITICAL / EXIT 判定
• conviction 銘柄の警告（thesis に conviction_override がある銘柄）

朝サマリーとの違い

データ保存

結果は data/session_logs/routine/ に自動保存する:

• daily_YYYYMMDD.json / weekly_YYYYMMDD.json

Conviction 違反検知（KIK-729）

Strategist 出力後、オーケストレーター自身が以下を自動実行する:

1. notes.load_notes(note_type="thesis") で conviction 銘柄リストを取得
   • thesis の content に「ホールド確定」「うらない」「conviction」を含む or source が user-conviction* で始まるもの
2. Strategist 出力テキストから売却提案銘柄を抽出（売却/手放す/撤退/損切りキーワード周辺の銘柄ティッカー）
3. 売却提案リストと conviction 銘柄が交差する場合、context: conviction_violation をセット
4. auto_review.trigger.context: conviction_violation がマッチ → Reviewer を強制起動

重要: conviction違反検知は意識ベースではなく仕組みで強制する。orchestrator はサブエージェント完了後、必ずこのチェックを実行する。

Thesis Check（KIK-715）

HC / Strategist 完了後、PF銘柄の thesis 参照を機械的に検証する。orchestration.yaml の thesis_check で定義され、auto_review より前に実行される。

1. load_notes(note_type="thesis") で全PF銘柄の thesis を取得
2. thesis 存在銘柄で出力に thesis 参照がない → ⚠️「thesis未参照」をユーザーに通知
3. thesis 未登録銘柄がある → ⚠️「テーゼ未登録: [銘柄名]」を通知
4. PF外の単発分析時はスキップ（skip_condition: no_portfolio_context）

History Check（KIK-740）

投資判断（売却/購入/入替/リバランス/損切り/利確等）を含む銘柄分析時に、4LLM並列で過去の歴史的類似事例を自動チェックする。LLM内蔵知識+Web検索を活用し、ライブラリ蓄積は行わない。

発動条件（自動）

以下のいずれかに該当 → history_check 自動発動:

1. routing.yaml の該当パターンに history_check: true フラグがある
2. ユーザー入力に投資判断キーワードが含まれる:
   • 売却 / 損切り / 利確 / 手放す / 撤退
   • 購入 / 買増し / 新規エントリー
   • 入替 / リバランス / 改善 / 調整
   • 「歴史」「過去」「事例」「パターン」（明示要求）

発動しないケース（重要）

• 単純な情報照会（「PER何？」「VIX確認」「トヨタどう？」等）
• 朝サマリー / mode: routine-* （ノイズ回避）
• 単独 health-checker / risk-assessor の実行
• conviction銘柄に対する「保有確認」レベルの問い合わせ

4LLM並列の役割分担

オーケストレーターが APIキー設定済みの LLM のみ並列起動する（graceful degradation）。

APIキー検出ロジック: os.environ.get('OPENAI_API_KEY'), GEMINI_API_KEY, XAI_API_KEY が未設定なら該当LLMをスキップ。Claude（自身）は常に動作。

責務の所在:

• APIキー検出はオーケストレーター層で実施（各LLM呼び出しの前に判定）
• 未設定でもエラーにせず、利用可能LLMのみで実行（graceful degradation）
• 利用可能LLMが Claude（自身）のみの場合、その旨を出力に明記して内部知識のみで実行

データ不足時のフォールバック:

• 「失敗例 ≥2件」「成功例 ≥1件」の最低件数を満たせない場合、推測で補完せず「該当事例なし（データ不足）」と明記
• 各LLMが独立に判定。1つでも基準未達なら統合判断に「データ不足」フラグを立てる

共通プロンプト テンプレート

銘柄: {symbol}
状況サマリー: {context}
  業績: {earnings_summary}
  株価: {price_summary}
  ファンダメンタルズ: {fundamentals}
  関連lesson: {lessons}
判断テーマ: {decision_theme}
  例: 売却検討 / 入替検討 / 損切り判断

過去の歴史的類似事例を以下の構造で挙げてください:
- 成功例（最低1件）: 同じ状況から立ち直った企業、その要因
- 失敗例（最低2件）: 同じ状況で衰退・破綻した企業、その要因
- 当該銘柄との類似度評価（高/中/低）+ 根拠
- 反証ポイント（盲信回避のため、必ず提示）

結果統合（Claudeが裁定）

各LLMの指摘を以下の構造に分類:

## 📚 歴史的類似事例

### 全LLM一致点
- ...

### 意見が割れた点（食い違いハイライト）
- Claude: ...
- GPT: ...
- Gemini: ...
- Grok: ...

### 統合判断
- 最終判断: ...
- 反証パターン: ...

⚠️ MUST: 成功例だけ/失敗例だけの片寄せ提示は禁止。必ず両論併記。 ⚠️ MUST: 反証ポイントを必ず含める（盲信回避）。

並列起動パターン

オーケストレーターが1メッセージで複数の LLM を同時呼び出し:

# オーケストレーター内（疑似コード）
import asyncio  # 並列はBashで複数のpython3 -cを同時発火、または
# 個別Bash run_in_background=True で並列化

# 実装上は Bash の run_in_background=True を3つ並列発火
Bash(call_llm gpt, run_in_background=True)
Bash(call_llm gemini, run_in_background=True)
Bash(grok search_market, run_in_background=True)
# Claude自身は内部知識で同時に思考
# 完了後に統合

DeepThink との差別化

ルール: history_check で十分な場合は DeepThink を使わない。複数の不確実性が絡む場合のみ DeepThink へ。

二重実行防止

同一セッションで既に history_check が実行済みの場合はスキップする。

Reviewer 起動方針（KIK-659 / KIK-729 で再設計）

エージェント実行後、orchestration.yaml の auto_review / adhoc_review ルールに従い Reviewer 起動を3分類で制御する。

3分類

agent_includes のセマンティクス: agents 配列（連鎖・並列を含む）に対象エージェントが含まれていればマッチ。例えば agents: [health-checker, strategist] の連鎖は agent_includes: strategist にマッチして adhoc_review が発動する。agent_only は配列長 == 1 かつそのエージェントのみの場合にマッチ（skip_review で使用）。

アドホック起動時のUX

🔍 Reviewer実行中...
  ├─ Risk (GPT)    ⏳
  ├─ Logic (Gemini) ⏳
  └─ Data (Claude)  ⏳

結果フォーマット:

• ✅ PASS → 「3観点 LGTM」1行のみ
• ⚠️ WARN → 観点別に1行 + 該当箇所引用 + 「無視/反映」選択
• ❌ FAIL → FAIL理由 + 修正方針案 + 承認待ち（既存 retry_on_fail 踏襲）

二重実行防止: 同一セッションで既に Reviewer が実行済みの場合はスキップする。

Reviewer 起動時の lesson 注入

Reviewer を起動する前に tools/notes.py の load_notes(note_type="lesson") でローカルの lesson を取得し、prompt に含める。 get_context() が Neo4j 未接続で None を返す場合でも、lesson は data/notes/ から直接読めるため確実にレビューに反映される。

# Reviewer の prompt に渡す情報
1. agent.md + examples.yaml の内容
2. レビュー対象（前段エージェントの出力全文）
3. ユーザーの入力（元の意図）
4. 過去の lesson 一覧（load_notes(note_type="lesson") で取得）

Direct Actions（記録系操作）

routing.yaml で action: direct に分類される操作はエージェント不要。オーケストレーターが直接実行する。

書く

判断不要のデータ操作なのでエージェントは起動しない。

読む（各エージェントが GraphRAG 経由で取得）

データ同期（KIK-676/677）

「sync して」「データを同期して」「整合性チェック」でローカル→GraphRAG の差分検出・同期を実行する。

同期フロー:

1. data/sync_status.yaml の last_sync を確認
2. last_sync より新しいファイルを差分として検出
3. 差分テーブルをユーザーに提示
4. ユーザー確認後、ローカル → GraphRAG の方向で同期実行
5. data/sync_status.yaml を更新

同期対象:

同期方向は常にローカル → GraphRAG（一方向）。 重複防止: graph_store の全関数が MERGE を使用。同じ id は上書きされ二重登録されない。

ベクトル埋め込み生成: sync 時に TEI（src/data/embedding_client.py）が利用可能であれば、各データの semantic_summary からベクトル埋め込みを生成し、GraphRAG ノードに付与する。これにより「前に調べた半導体関連」のような曖昧なベクトル検索が可能になる。TEI 未起動時は埋め込みなしで同期する（graceful degradation）。

データ保存原則

• マスター: data/ (JSON/CSV) — 常に保存。GraphRAG の有無に関わらない
• ビュー: GraphRAG / Neo4j（dual-write、接続時のみ）
• GraphRAG がなくても動作する（graceful degradation）

Orchestration（自律修正ループ）

orchestration.yaml に従い、エージェント実行後の自動リトライ・エスカレーションを制御する。

• スクリーニング0件 → 条件緩和して自律リトライ（最大2回）
• Reviewer PASS/WARN → そのまま出力（自律）
• Reviewer FAIL → FAIL理由と修正方針案をユーザーに提示 → 承認後リトライ（最大2回）
• 再試行上限到達 → 現時点の結果をそのまま提示

Post-Action

1. 結果をユーザーに提示

エージェントの出力をユーザーに提示する。Reviewer の自動挿入は orchestration.yaml の auto_review で制御。

2. データ保存（自律実行）（KIK-674）

エージェント実行後、結果を以下に保存する。ユーザーの指示を待たず自律的に実行する。

データ保存原則:

• data/ (JSON/CSV) は常に保存する。 これが唯一の自動保存先
• GraphRAG への書き込みは自動実行しない。 ユーザーが「sync して」と指示した場合のみ実行する
• 保存の最終責任はオーケストレーターが持つ。 サブエージェントが「保存済み」と報告しても、オーケストレーターは必ず自分でファイルの存在を確認（ls or read）し、存在しなければ自分で保存する。サブエージェントの報告を鵜呑みにしない（保存処理が失敗している可能性がある）

保存ステータス表示:

データ保存後、以下のステータスをユーザーに必ず表示する:

💾 data/screening_results/trending_us_20260420.json

sync 提案（Neo4j 接続時のみ）:

データ保存後、Neo4j が接続中であれば「sync しますか？」とユーザーに確認する。 Neo4j 未接続時は提案しない（graceful degradation）。

# Neo4j 接続判定
from src.data.graph_store._common import is_available
if is_available():
    # → 「💾 保存しました。sync しますか？」と提案

ユーザーが承認した場合のみ、下記「3. データ同期」を実行する。

3. データ同期（sync）

ユーザーから「sync して」「GraphRAG と同期」と指示された場合、または上記の sync 提案をユーザーが承認した場合、data/ → GraphRAG の一方向同期を実行する。

sync 対象:

sync 状態管理: data/sync_status.yaml で最終同期日時と同期済みファイル一覧を管理。ファイルの更新日時が last_sync より新しければ未同期と判定。

重複防止: graph_store の全関数が Neo4j の MERGE を使用。同じ id のデータは上書きされるため、初回 full sync でも二重登録されない。

4. 学びの記録提案

エージェント実行後、結果に学び・教訓・気づきがあると判断できる場合、ユーザーに「記録しますか？」と提案する。

提案条件（いずれかに該当）:

• Reviewer が WARN/FAIL を出した（失敗パターンの記録価値あり）
• 過去の lesson と矛盾する結果が出た
• ユーザーが意外な反応をした（想定外の判断・確信）
• スクリーニングで新しいテーマ・観点が出た

提案フォーマット:

📝 学びを記録しますか？
例: 「防衛株は地政学イベントで必ず上がるわけではない」

保存フロー:

1. ユーザーが承認 → tools/notes.py の save_note(note_type="lesson") で data/notes/ に保存
2. Neo4j 接続中 → 保存後そのまま GraphRAG にも sync（merge_note()）
3. Neo4j 未接続 → data/ のみ保存（次回 sync 時に反映）

記録しない場合: ユーザーが不要と判断すればスキップ。強制しない。

5. 次のアクションを提案

• 次の自然なアクションを1-2個提案する
• 直前の会話で扱った銘柄・結果を引き継ぎ、省略された情報を補完する

Layer 5: Cited Sources (KIK-739)

「何に依拠して結論を出したか」を可視化することで、古い情報の生ゴミ化を防ぐ。 2026-04-28 セッション (META 推奨ミス・AVGO/NEE ATH 見落とし) の根本対策。

適用条件 (Layer 5 を出すべきパターン)

• 投資判断 / 売買提案 / トリム / リバランスを含む
• DeepThink Step 5 出力
• Strategist agent の最終提案
• routine-weekly レポート
• routing.yaml の該当 routing で layer5: required フラグがある場合

逆に 不要なケース: health-checker 単独 / risk-assessor 単独 / 単純な事実照会 (Pattern A 軽量) は Layer 5 をスキップしてよい。

出力フォーマット

src/data/citation_formatter.format_cited_sources(cited_lessons, cited_theses, used_for_map) が markdown ブロックを返す。本文末尾に追加するだけ。

## 📚 Cited Sources

### Lessons
- 🟢 [permanent] 2026-04-24 PFバランス normal — Cash 15-20% 判定
- 🟢 [permanent] 2026-04-25 7751.T HOLD-LOCK — 売却対象除外
- 🟡 [seasonal/45日] 2026-03-22 金利4%超ヘッジ — 金利感応度判定 ⚠ 古い: 環境変化あれば再確認

### Theses
- 🔒 [conviction] 2026-04-25 7751.T ホールド確定
- 🟢 2026-04-24 MSFT 投資テーゼ — 押し目買い増し根拠

鮮度マーカー規則

引用判定 (citation 抽出)

DeepThink Step 5 で verify_lesson_cited() (KIK-738) が成功したリストから自動抽出:

cited_lessons = [l for l in relevant_lessons if l.get("id") not in missing_lesson_ids]

verify が abort した時点で 1 件も citation がない状態は発生しない (lesson 形骸化阻止)。

References

• ルーティング few-shot: routing.yaml
• 自律修正ループ: orchestration.yaml
• Citation formatter: src/data/citation_formatter.py