section-merger

セクションの結合

トリガーとルーティング

• トリガー：セクションを結合する、草稿を結合する、セクションファイルをまとめる、sections/ -> output/DRAFT.md、小節を結合する、草稿をつなげる。
• 使用する場面：sections/ に単位ごとの文章ファイルがあり、推敲・レビュー・LaTeX 用に単一の output/DRAFT.md を作成したい場合。

目的は、以下から論文形式の output/DRAFT.md を作成することです。

• sections/（セクション／サブセクションごとの文章）
• outline/transitions.md（任意の接続候補。transition-weaver が生成）
• outline/tables_appendix.md（読者向けの付録表。appendix-table-writer が生成）

結合順序は outline/outline.yml によって決まります。草稿のタイトルは、 GOAL.md がある場合はそこから取得します。Pipeline の契約によって sections/sections_manifest.jsonl が指定されている場合、結合するすべてのセクションは 記録されたバイト数と SHA-256 ハッシュに一致する必要があります。

このスキルは決定論的です。コンテンツを書き換えたり文章を作成したりせず、生成済みの成果物を結合するだけです。

トランジション（明示的なオプトイン）

• デフォルトでは、生成されたトランジションは挿入されません。
• H3 のトランジションを挿入するには、outline/transitions.insert_h3.ok を作成します。
• H2 のトランジションを挿入するには、outline/transitions.insert_h2.ok を作成します。
• 書式の契約：H3 の項目には - 3.1 -> 3.2: <text> を使用します。
• 互換性：→ も使用できますが、制御文字のエンコード問題を避けるため、契約では -> を推奨します。
• トランジションは草稿に挿入されたテキストとして扱います。結合後に post-merge-voice-gate を実行し、修正は outline/transitions.md に反映します（結合済みの草稿は修正しないでください）。

表（2 層）

この Pipeline では、次の 2 層の表を使用します。

• outline/tables_index.md（内部インデックス。table-filler が生成）

  • 計画／デバッグ用の成果物
  • 論文に挿入しないでください

• outline/tables_appendix.md（読者向けの付録表。appendix-table-writer が生成）

  • 公開可能な表（整ったレイアウトと高い情報密度）
  • section-merger によって、単一の付録見出しの下に挿入されます

付録の挿入動作

• section-merger は、草稿の末尾に ## Appendix: Tables という見出しを付けて outline/tables_appendix.md を挿入します。
• 挿入されるブロックには見出しがありません（表ファイル内に誤って含まれている # 見出しはすべて削除されます）。
• オプトアウト（まれ）：ワークスペース内に outline/tables.insert.off を作成します。

入力

• outline/outline.yml（セクション／サブセクションの順序を決定）
• outline/transitions.md（必須）
• sections/sections_manifest.jsonl（実行可能な survey Pipeline で必須。鮮度ゲート）
• GOAL.md（タイトル用。任意）

arxiv-survey Pipeline の場合（デフォルトの契約）：

• outline/tables_appendix.md（オプトアウトしない限り必須）

出力

• output/DRAFT.md
• output/MERGE_REPORT.md

スクリプト

クイックスタート

• uv run python .codex/skills/section-merger/scripts/run.py --help
• uv run python .codex/skills/section-merger/scripts/run.py --workspace <workspace>

すべてのオプション

• --workspace <workspace>（必須）
• --unit-id <id>（任意。ランナーの記録管理にのみ使用）
• --inputs <a;b;c>（任意。入力を上書き。デフォルトはプロファイルに応じて決定）
• --outputs <draft_rel;report_rel>（任意。デフォルトは output/DRAFT.md;output/MERGE_REPORT.md）
• --checkpoint <C#>（任意。マージャーでは無視されます）

例

• デフォルト設定で結合（プロファイルに応じた表の挿入）：

  uv run python .codex/skills/section-merger/scripts/run.py --workspace <workspace>

• 出力先を明示して結合：

  uv run python .codex/skills/section-merger/scripts/run.py --workspace <workspace> --outputs output/DRAFT.md;output/MERGE_REPORT.md

トラブルシューティング

問題：マージレポートにサブセクションファイルが見つからないと表示される

考えられる原因：

• 必須の sections/*.md ファイルがまだ作成されていません。

解決方法：

• sections/ に不足している単位のファイルを作成し（通常は subsection-writer を使用）、結合を再実行します。

問題：統合されたドラフトで付録の表が欠落しています

修正方法：

• outline/tables_appendix.md が存在し、プロファイルに応じた最低数の表（コース論文：1 つ以上、サーベイ／詳細調査：2 つ以上）が含まれ、プレースホルダーがないことを確認します。
• outline/tables.insert.off を作成していないことを確認します。
• section-merger を再実行します。