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)
  • By default, section-merger inserts only within-chapter H3→H3 transitions (keeps flow without adding narrator paragraphs between chapters).
  • 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 (within-chapter H3 → next H3); keep <text> as one sentence.
  • 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).
  • Keep transitions paper-like (argument bridges), not title narration (avoid "From X to Y" / "Now we turn to").
  • If transitions feel templated, fix outline/subsection_briefs.jsonl (bridge_terms/contrast_hook) and regenerate via transition-weaver.

Evidence-first visuals (outline/tables.md, outline/timeline.md, outline/figures.md) are intermediate artifacts by default. If you want them in the final PDF, weave them into the relevant prose sections intentionally (instead of auto-injecting them as top-level ToC chapters).

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

Inputs

• outline/outline.yml (drives section/subsection order)
• outline/transitions.md (required; generated by transition-weaver)
• Optional (diagnostics): sections/sections_manifest.jsonl
• Optional context: GOAL.md

Outputs

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

Workflow (deterministic)

1. Read GOAL.md (if present) and use its first non-heading line as the draft title.
2. Read outline/outline.yml to determine the expected section/subsection order.
3. Merge the per-unit files under sections/.
4. Insert transitions from outline/transitions.md (within-chapter H3→H3 by default; between-H2 only if outline/transitions.insert_h2.ok exists).
5. Write output/DRAFT.md and a deterministic output/MERGE_REPORT.md (missing files, ordering).

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 <dir>: workspace root
• --unit-id <U###>: unit id (optional; for logs)
• --inputs <semicolon-separated>: override inputs (rare; prefer defaults)
• --outputs <semicolon-separated>: override outputs (rare; prefer defaults)
• --checkpoint <C#>: checkpoint id (optional; for logs)

Examples

• Standard merge (outline + transitions + section files):
  • python .codex/skills/section-merger/scripts/run.py --workspace workspaces/<ws>

Troubleshooting

Issue: merge report says a subsection file is missing

Likely cause:

• A required sections/*.md file has not been written yet (check sections/sections_manifest.jsonl if present to see which units exist).

Fix:

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