section-merger

Section Merger

Triggers & routing

Trigger: merge sections, merge draft, combine section files, sections/ -> output/DRAFT.md, merge subsections, concatenate draft.
Use when: you have per-unit prose files under sections/ and want a single output/DRAFT.md for polishing/review/LaTeX.

Goal: assemble a paper-like output/DRAFT.md from:

sections/ (per-section/per-subsection prose)
outline/transitions.md (optional hand-off suggestions; 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 derived from GOAL.md when present. When sections/sections_manifest.jsonl is supplied by the Pipeline contract, every merged section must match its recorded bytes and SHA-256 hash.

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

Transitions (explicit opt-in)

By default, generated transitions are not inserted.
To insert H3 transitions, create outline/transitions.insert_h3.ok.
To insert H2 transitions, create outline/transitions.insert_h2.ok.
Format contract: H3 entries use - 3.1 -> 3.2: <text>.
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 (required by the executable survey Pipeline; freshness gate)
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

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

All Options

--workspace <workspace> (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):

uv run python .codex/skills/section-merger/scripts/run.py --workspace <workspace>
Merge with explicit outputs:

uv run python .codex/skills/section-merger/scripts/run.py --workspace <workspace> --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