Section Merger

Section Merger

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

Fix:

• Ensure outline/tables_appendix.md exists and contains the profile minimum

(course paper: >=1; survey/deep: >=2) with no placeholders.

• Ensure you did not create outline/tables.insert.off.
• Rerun section-merger.