| name | section-merger |
| description | Deterministically merge the final fingerprinted section snapshot into `output/DRAFT.md`, preserving outline order and inserting transitions only when explicitly enabled.
**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.
|
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:
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.mdoutput/MERGE_REPORT.md
Script
Quick Start
uv run python .codex/skills/section-merger/scripts/run.py --helpuv 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.
