@willoscar/section-merger

---
name: section-merger
description: |
  Deterministically merge per-section files under `sections/` into `output/DRAFT.md`, preserving outline order and weaving transitions from `outline/transitions.md`.
  **Trigger**: merge sections, merge draft, combine section files, sections/ -> output/DRAFT.md, 合并小节, 拼接草稿.
  **Use when**: you have per-unit prose files under `sections/` and want a single `output/DRAFT.md` for polishing/review/LaTeX.
  **Skip if**: section files are missing or still contain scaffolding markers (fix `subsection-writer` first).
  **Network**: none.
  **Guardrail**: deterministic merge only (no new facts/citations); preserve section order from `outline/outline.yml`.
---

# Section Merger

Goal: assemble a paper-like `output/DRAFT.md` from:
- `sections/` (per-section/per-subsection prose)
- `outline/transitions.md` (short hand-offs; generated by `transition-weaver`)
- `outline/tables_appendix.md` (reader-facing Appendix tables; generated by `appendix-table-writer`)

Merge order is driven by `outline/outline.yml`. The draft title is taken from `GOAL.md` when present. `sections/sections_manifest.jsonl` is an optional diagnostics input.

This skill is deterministic: it does not rewrite content or invent prose; it only merges already-generated artifacts.

## Transitions (injected text)

- By default, `section-merger` inserts only within-chapter H3->H3 transitions.
- Optional: if you want between-H2 transitions inserted too, create `outline/transitions.insert_h2.ok` in the workspace.
- Format contract: only lines matching `- 3.1 -> 3.2: <text>` are injected by default.
- Compatibility: `→` is accepted, but `->` is the preferred contract (avoids control-character encoding issues).
- Treat transitions as injected draft text: run `post-merge-voice-gate` after merging, and route fixes back to `outline/transitions.md` (do not patch the merged draft).

## Tables (two layers)

This pipeline uses two table layers:

- `outline/tables_index.md` (internal index; produced by `table-filler`)
  - planning/debugging artifact
  - should NOT be inserted into the paper

- `outline/tables_appendix.md` (reader-facing Appendix tables; produced by `appendix-table-writer`)
  - publishable tables (clean layout + high information density)
  - inserted by `section-merger` under a single Appendix heading

### Appendix insertion behavior

- `section-merger` inserts `outline/tables_appendix.md` at the end of the draft under `## Appendix: Tables`.
- The inserted block is heading-free (any accidental `#` headings inside the tables file are stripped).
- Opt-out (rare): create `outline/tables.insert.off` in the workspace.

## Inputs

- `outline/outline.yml` (drives section/subsection order)
- `outline/transitions.md` (required)
- `sections/sections_manifest.jsonl` (optional diagnostics)
- `GOAL.md` (optional title)

For arxiv-survey pipelines (default contract):
- `outline/tables_appendix.md` (required unless opted out)

## Outputs

- `output/DRAFT.md`
- `output/MERGE_REPORT.md`

## Script

### Quick Start

- `python .codex/skills/section-merger/scripts/run.py --help`
- `python .codex/skills/section-merger/scripts/run.py --workspace workspaces/<ws>`

### All Options

- `--workspace <workspace_dir>` (required)
- `--unit-id <id>` (optional; used only for runner bookkeeping)
- `--inputs <a;b;c>` (optional; override inputs; defaults are profile-aware)
- `--outputs <draft_rel;report_rel>` (optional; defaults to `output/DRAFT.md;output/MERGE_REPORT.md`)
- `--checkpoint <C#>` (optional; ignored by the merger)

### Examples

- Merge with defaults (profile-aware table insertion):

  `python .codex/skills/section-merger/scripts/run.py --workspace workspaces/<ws>`

- Merge with explicit outputs:

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

## Troubleshooting

### Issue: merge report says a subsection file is missing

Likely cause:
- A required `sections/*.md` file has not been written yet.

Fix:
- Write the missing units under `sections/` (typically via `subsection-writer`) and rerun merge.

### Issue: Appendix tables are missing in the merged draft

Fix:
- Ensure `outline/tables_appendix.md` exists and contains >=2 Markdown tables (no placeholders).
- Ensure you did not create `outline/tables.insert.off`.
- Rerun `section-merger`.