section-mapper

Section Mapper

トリガーとルーティング

• トリガー：section mapper、mapping.tsv、coverage、paper-to-section mapping、论文映射、覆盖率。
• 使用する場面：構成段階（C2）で、papers/core_set.csv と outline/outline.yml がすでにあり、evidence／執筆に進む前に各小節に十分な根拠となる論文があることを確認する必要がある場合。

根拠の構築と後の統合に役立つ、論文→小節のマップを作成します。

適切なマッピングは、関連性が高く、多様性があり、説明可能です。コーパス全体にわたるトピック語や、アウトラインで繰り返される定型文は、小節との関連性を示す根拠にはなりません。

使用する場面

• outline/outline.yml と papers/core_set.csv があり、小節ごとのカバレッジを把握する必要がある場合。
• シグナルの弱い小節を早期に特定したい場合（スコープの調整や論文の追加ができます）。

入力

• papers/core_set.csv
• outline/outline.yml

出力

• outline/mapping.tsv
• outline/mapping_report.md（診断情報：再利用が集中している箇所、シグナルの弱い小節）
• outline/mapping_gap_candidates.tsv（コアセットでは小節ごとの目標を満たせない場合に、重複除去済みプールから作成する読み取り専用の補修候補）

凍結マーカー（明示的）

マッピングの理由を精査した後に、誤って上書きされるのを防ぐには：

• outline/mapping.refined.ok を作成します。

このマーカーが有効なのは、マッピング、コアセット、アウトライン、クエリ契約、マッパーの実装より新しい場合に限られます。上流の変更があると、マーカーは無効になります。

このマーカーなしでスクリプトを再実行すると、以前のマッピングはタイムスタンプ付きファイルにバックアップされます：

• outline/mapping.tsv.bak.<timestamp>

ワークフロー（ヒューリスティック）

1. アウトラインの小節から始めます（各小節は「マッピング可能」である必要があります）。
2. 各小節について、根拠を優先した執筆を支えるのに十分な論文（A150++ のデフォルト：28 件、小規模な実行：～12～20 件、軽量：～3～6 件）を選びます。論文は次の条件を満たす必要があります：
   • 代表性がある（標準的／頻繁に引用されている）
   • 相補的である（設計上の選択や評価設定が異なる）
   • 真に基礎的な論文でない限り、他の小節で過度に再利用されていない
   • トピック全体の名称など、コーパス全体にわたる語だけでなく、小節固有の概念によって裏付けられている
3. why には、短い意味的な根拠を記入します（1 行で十分です）。例：
   • メカニズム：「プランナーとエグゼキューターを分離；ツール呼び出し API」
   • 評価：「対話型ウェブタスク；ツールエラーの詳細な分析」
   • 安全性：「エージェント型のジェイルブレイク対象領域；緩和策の研究」
4. 最初のマッピング後、次の点を確認します：
   • 論文が 3 件未満の小節 → 範囲を広げる、統合する、または検索範囲を拡大します
   • あらゆる小節にマッピングされている論文が少数ある → 多様化します。「基礎的」な論文は、本当に関連する箇所にのみ割り当てます
   • 目標に達していない箇所 → 根拠のギャップとして扱います。行数を満たすためだけに無関係な論文を割り当てないでください

品質チェックリスト

• outline/mapping.tsv が存在し、空ではない。
• ほとんどの小節に 3 件以上の論文がマッピングされている（または why に明確な例外理由が記載されている）。
• why が意味的な根拠になっている（matched_terms=... だけではない）。
• 特定の 1 件の論文が、無関係な小節を支配していない。
• 根拠のギャップを隠すために、確信度の低い穴埋め用の行を使っていない。

ヘルパースクリプト（任意）

クイックスタート

• uv run python .codex/skills/section-mapper/scripts/run.py --help
• uv run python .codex/skills/section-mapper/scripts/run.py --workspace <workspace> --per-subsection 28

すべてのオプション

• --per-subsection <n>：小節ごとにマッピングする論文の目標数
• --diversity-penalty <int>：同じ論文が多くの小節で繰り返し再利用されることにペナルティを課します
• --soft-limit <n> / --hard-limit <n>：論文ごとの再利用上限（0 = 自動）
• --minimum-score <n>：自動関連性しきい値（デフォルト：3）；生成されたマッピングを手動で確認する場合にのみ下げてください

例

• 多様性を高める（過剰な再利用を減らす）：
  • uv run python .codex/skills/section-mapper/scripts/run.py --workspace <workspace> --per-subsection 4 --diversity-penalty 5
• 再利用上限を厳しくする：
  • uv run python .codex/skills/section-mapper/scripts/run.py --workspace <workspace> --per-subsection 3 --soft-limit 6 --hard-limit 10

注意事項

• 診断結果を outline/mapping_report.md に書き込みます。
• papers/core_set.csv を暗黙に変更する代わりに、outline/mapping_gap_candidates.tsv に書き込みます。凍結されたコアセットの変更は、人間またはキュレーション工程が引き続き担当します。
• コーパス全体およびアウトライン全体に共通する用語をスコアリング前に除外し、小見出しとの整合性を重視して、セクション固有の根拠が不十分な候補は採用しません。
• オプションの assets/domain_packs/*.json ルールを使うと、明示的に検出されたドメインについて、曖昧な小見出しラベルをより厳密にできます。これらのルールはマッピングを制約するものであり、コアセットは変更しません。
• pipeline.py --strict では、一般的な why の根拠が意味に基づくものに置き換えられるまで、マッピングがブロックされる場合があります。

トラブルシューティング

よくある問題

問題：outline/mapping.tsv が空、または網羅率が低い

症状:

• マッピングの行数が少ない、または論文が3本未満の小見出しが多数あります。

原因:

• コアセットが小さすぎるか、アウトラインが細分化されすぎています。

解決策:

• コアセットのサイズを増やします（より大きな --core-size を指定して dedupe-rank を再実行します）。
• シグナルの弱い小見出しを統合するか、スコープ／クエリの範囲を広げます。

問題：マッピングで同じ論文が繰り返し使われる

症状:

• 品質ゲートで、関連のない多くの小見出しに同じ論文が繰り返し割り当てられていると報告されます。

原因:

• 多様性ペナルティが低すぎる、またはコアセットが限られています。

解決策:

• --diversity-penalty の値を上げる、またはより厳しい --soft-limit/--hard-limit を設定します。
• 関連のないセクションのマッピングを手動で多様化します。

復旧チェックリスト

• 各小見出しに論文が3本以上マッピングされている（目標）。
• why 列に意味に基づく根拠が記載されている（トークンの重複だけではない）。