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 .