Lossless Changelog
component

Canonical Draft Assembly Tool

Three CLI tools each had their own way of stitching a memo back together, so citation numbers collided and the table of contents went stale. Now there is one assembler, and everything else delegates to it.

Changelog - 2025-11-28 (#3)

Canonical Draft Assembly Tool

Type: Refactor / New Feature Priority: HIGH

Summary

Created cli/assemble_draft.py as the single source of truth for assembling 4-final-draft.md from section files. All CLI tools that modify sections now delegate to this tool, ensuring consistent formatting:

  1. Citation renumbering (no collisions across sections)

  2. Citation consolidation (all references at document end)

  3. Table of Contents generation (accurate, with anchor links)

Problem

Multiple CLI tools had their own reassemble_final_draft() functions with inconsistent behavior:

  • cli/improve_section.py - Simple concatenation, no citation handling, no TOC

  • cli/improve_team_section.py - Simple concatenation, no citation handling, no TOC

  • src/agents/key_info_rewrite.py - Had citation handling but was duplicating logic

This caused formatting issues when using CLI tools:

  • Citations appeared at section level with number collisions

  • TOC was missing or outdated after section modifications

  • Inconsistent output quality between main workflow and CLI tools

Solution

New Tool: cli/assemble_draft.py

Canonical assembly function that handles all formatting invariants:

BASH
# Standalone usage
python -m cli.assemble_draft "Sava"
python -m cli.assemble_draft "Sava" --version v0.0.2
python -m cli.assemble_draft output/Sava-v0.0.2

# Programmatic usage
from cli.assemble_draft import assemble_final_draft
final_path = assemble_final_draft(artifact_dir, console)

Assembly steps:

  1. Load header.md (company trademark) if exists

  2. Load all sections from 2-sections/ in order

  3. Renumber citations globally ([^1], [^2]... sequentially)

  4. Consolidate all citation references into ONE block at document end

  5. Remove any existing TOC to prevent duplication

  6. Generate fresh Table of Contents with anchor links

  7. Save polished 4-final-draft.md

Updated CLI Tools

All tools now delegate to the canonical assembler:

cli/improve_section.py

PYTHON
def reassemble_final_draft(artifact_dir: Path, console: Console) -> Path:
    from cli.assemble_draft import assemble_final_draft as canonical_assemble
    console.print("\n[bold]Reassembling final draft...[/bold]")
    return canonical_assemble(artifact_dir, console)

cli/improve_team_section.py

  • Same delegation pattern

src/agents/key_info_rewrite.py

  • Same delegation pattern (removed 60+ lines of duplicated logic)

Files Changed

FileChange
cli/assemble_draft.pyCreated - canonical assembly tool
cli/improve_section.pyRefactored reassemble_final_draft() to delegate
cli/improve_team_section.pyRefactored reassemble_final_draft() to delegate
src/agents/key_info_rewrite.pyRefactored reassemble_final_draft() to delegate

Testing

BASH
# Test standalone assembly
python -m cli.assemble_draft "Sava"
# Output: ✓ Final draft assembled: output/Sava-v0.0.1/4-final-draft.md
#         Words: 8,945 | Citations: 38

python -m cli.assemble_draft "Sava" --version v0.0.2
# Output: ✓ Final draft assembled: output/Sava-v0.0.2/4-final-draft.md
#         Words: 10,704 | Citations: 43

This changelog is part of a series of improvements made on 2025-11-28:

  1. 2025-11-28_01.md - Initial Sava memo generation

  2. 2025-11-28_02.md - Entity disambiguation system

  3. 2025-11-28_03.md - Canonical draft assembly tool (this file)

Also created today:

  • cli/improve_team_section.py - Sequential team research tool

  • context-vigilance/Containerizing-Risk-Assessments-and-Diligence-Skepticism.md - Spec for separating conviction from skepticism content