portfolio-drift-rebalancer

ポートフォリオの乖離リバランサー

目次

• 概要
• 入力仕様
• ワークフロー
• 税効率を考慮したリバランスロジック
• 出力仕様
• ガードレール

概要

一般的に、世帯では課税対象の証券口座（例：Fidelity）、401k、HSA の投資部分という 3 種類の口座に投資を保有しています。目標配分は世帯全体で定義します（例：米国株式／海外株式／債券／現金を 55／20／20／5）。このスキルは、3 つすべての口座にわたる現在の配分を集計し、目標からの乖離を計算して、目標配分に戻すための具体的な買い注文と売り注文を提案します。その際、実現益に税金がかからない税制優遇口座（401k、HSA）内での取引を優先します。

取引を実行することはありません。 ユーザー向けに提案を作成します。

入力仕様

呼び出し元は、以下を指定します。

• accounts — 投資口座の配列：{id, type, institution, holdings[]}。各保有資産は{symbol, shares, value_cents, cost_basis_cents, asset_class}を持ちます。
• target_allocation — 合計が 1.0 となる{ asset_class: target_pct }。
• drift_threshold_pct — デフォルトは 5 パーセントポイント（5.0）です。このしきい値未満の場合、リバランスは提案されません。
• cash_to_deploy_cents — 追加で入金される現金（例：給与振込）を指定する任意項目です。
• tax_rate_long_term — コスト比較の概算に使用します（デフォルトは 15%）。

ワークフロー

Drift / Rebalance Progress:
- [ ] Step 1: Aggregate holdings by asset_class across all accounts
- [ ] Step 2: Compute current allocation percentages
- [ ] Step 3: Compute drift vs target
- [ ] Step 4: Check drift threshold; if all classes within threshold, return no-op
- [ ] Step 5: If new cash, allocate it preferentially to under-target classes
- [ ] Step 6: For remaining drift, plan trades
- [ ] Step 7: Order trades by tax cost (advantaged-account first)
- [ ] Step 8: Verify proposal nets to zero cash impact (or matches new-cash deposit)
- [ ] Step 9: Emit proposal with per-trade rationale

ステップ 1 — 集計

目標に含まれる各asset_classについて、すべての口座の全保有資産にわたってvalue_centsを合計します。証券口座の現金ポジション（通常、asset_class はcash）も含めます。

ステップ 2 — 配分

current_pct[class] = total_value[class] / total_value_all。小数点以下 2 桁を保持します。

ステップ 3 — 乖離

drift_pp[class] = current_pct[class] − target_pct[class]をパーセントポイントで計算します。

ステップ 4 — しきい値

max(|drift_pp|)がdrift_threshold_pct未満の場合は、rebalance_needed: falseを出力して終了します。状況を把握できるよう乖離の値は提示しますが、取引は提案しません。

ステップ 5 — 新規現金の投入

cash_to_deploy_cents > 0の場合、目標未達の資産クラスに優先して配分します。目標未達の資産クラスに投入した新規現金は、1 ドルごとにステップ 6 で必要となる取引量を減らします。

配分順：drift_ppが最も小さいものから順にします。

ステップ 6 — 取引の計画

現金を投入した後も残る乖離に対して、取引を行います。目標超過の各資産クラスについてexcess_centsを、目標未達の各資産クラスについてshortfall_centsを計算します。貪欲法でペアを作成し（最大の超過と最大の不足を組み合わせ）、(sell_class, buy_class, amount_cents)のスワップ一覧を作成します。

ステップ 7 — 税効率を考慮した優先順位付け

各スワップでは、以下の優先順位で具体的な保有資産を選択します。

売却側の優先順位（優先度の高い順）：

1. 401kまたはhsa内の保有資産（売却しても税金はかかりません）。
2. 含み損のある課税対象証券口座の保有資産（売却により損失控除が可能な損失が発生します。tax-loss-harvest-scannerと連携してください）。
3. 含み益が最も小さい課税対象証券口座の保有資産（税コストが最も低くなります）。
4. 長期譲渡益のある課税対象証券口座の保有資産（15%の税率が適用されます）。
5. 短期譲渡益のある課税対象証券口座の保有資産（限界税率が適用されます）。

購入側の優先順位：

1. 希望する資産クラスの401kまたはhsa内の保有資産（取引に伴う税負担がありません）。
2. 希望する資産クラスの課税対象証券口座における既存の保有資産（売却したばかりの資産を買い戻さず、ウォッシュセールを回避します）。
3. 新規保有資産（幅広い市場を対象としたインデックスファンドを優先します）。

課税対象口座から提案する売却ごとに、税コストの概算値を計算して提示します：(value − cost_basis) × tax_rate_long_term。ユーザーは、リバランスによるメリットが税コストを上回るかどうかを判断できます。

ステップ 8 — 検証

提案は、Σ buys = Σ sells + cash_to_deploy_centsを満たす必要があります。満たさない場合は、計画にバグがあるため、proposal_invalid警告を出力して終了します。

ステップ 9 — 出力

取引ごとの出力には、口座、シンボル、アクション（買い／売り）、株数、金額、asset_classの変更、税コストの概算値、理由（目標未達／目標超過／新規現金の投入）を含めます。

税効率を考慮したリバランスロジック

口座	売却時の税コスト	備考
401k	$0	すべての売却が非課税です
HSA（投資済み）	$0	すべての売却が非課税です
証券口座（長期譲渡益）	利益の15%	保有期間が1年超
証券口座（短期譲渡益）	利益 × 限界税率	保有期間が1年未満 — 通常は避けます
証券口座（損失）	節税効果（TLH のメリット）	tax-loss-harvest-scanner と連携します

ウォッシュセールへの注意。 売却と同一の証券と実質的に同一の証券の購入が30日以内に行われる場合（配偶者の口座を含む、すべての口座で）、損失は認められません。リバランスで課税口座の ETF を損失で売却する場合、買い側では 異なるが類似した ETF を使用する必要があります（例：VTI を売却し、ITOT を購入）。各取引にウォッシュセール防止策を記録してください。

フリーマネーのフラグ — リバランスが不要な場合でも出力します。

• 401k の拠出率が雇用主のマッチング上限未満 → free_money_alert: missed_employer_match。
• HSA の現金残高が投資基準額を超えているのに投資されていない → free_money_alert: idle_hsa_cash。

出力仕様

{
  "as_of": "2026-04-25",
  "totals": {
    "portfolio_value_cents": 49250000,
    "by_account": {
      "acc_inv_fid_001": 18750000,
      "acc_401k_001": 22500000,
      "acc_hsa_001": 8000000
    }
  },
  "current_allocation": {
    "us_equity": 0.625,
    "intl_equity": 0.155,
    "us_bond": 0.180,
    "cash": 0.040
  },
  "target_allocation": {
    "us_equity": 0.55,
    "intl_equity": 0.20,
    "us_bond": 0.20,
    "cash": 0.05
  },
  "drift_pp": {
    "us_equity":  7.5,
    "intl_equity": -4.5,
    "us_bond":    -2.0,
    "cash":       -1.0
  },
  "rebalance_needed": true,
  "max_drift_pp": 7.5,
  "trades": [
    {
      "account_id": "acc_401k_001",
      "action": "sell",
      "symbol": "FXAIX",
      "asset_class": "us_equity",
      "value_cents": 1850000,
      "shares": 18.5,
      "tax_cost_cents": 0,
      "rationale": "Reduce US equity overweight using tax-advantaged account"
    },
    {
      "account_id": "acc_401k_001",
      "action": "buy",
      "symbol": "FSPSX",
      "asset_class": "intl_equity",
      "value_cents": 1850000,
      "shares": 41.0,
      "tax_cost_cents": 0,
      "rationale": "Increase intl equity to target via tax-advantaged account"
    }
  ],
  "alerts": [],
  "free_money": [
    {
      "type": "missed_employer_match",
      "account_id": "acc_401k_001",
      "current_contribution_pct": 3,
      "match_cap_pct": 4,
      "annual_dollars_left_cents": 200000,
      "action": "increase 401k contribution from 3% to 4%"
    }
  ]
}

ガードレール

• 決して実行しないでください。 このスキルが生成するのは提案のみです。
• ドリフトのしきい値には意味があります。 5パーセントポイント未満のドリフトはノイズです。これをリバランスすると、税金や取引の諸経費などの摩擦コストが発生します。
• 税コストを明示してください。 課税対象の売却にはすべて、推定税コストを明記します。ユーザーが確認できるようにしてください。
• ウォッシュセールを防止してください。 損失が出る売却には、実質的に同一ではない別の証券の購入を組み合わせます。内容を記録してください。
• 保有銘柄が端株に対応していない場合は、整数株のみとします。最も近い整数株に丸め、残余の現金を明示してください。
• 新たな現金を目標比率超過の資産クラスに自動投入しないでください。 取引を最小限に抑えられる場合でも、ドリフトが拡大します。目標比率を下回る資産クラスに投入してください。
• 口座単位の制約を遵守してください。 401k で購入できるのが特定のファンドに限られている場合、その口座で取り扱いのないファンドの購入を提案してはいけません。エージェント層は口座ごとの適格ファンド一覧を読み込みます。