docs/plans/2026-10-05-fill.md

Fill Paragraph Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: M-q as org-fill-paragraph: paragraphs (also in items and greater blocks), comments and comment blocks, byte- and caret-exact against Emacs.

Architecture: Fill.swift ports org-fill-element and Emacs's fill-region-as-paragraph (fill.el): adaptive prefixes (fill-context-prefix, fill-match-adaptive-prefix, org-adaptive-fill-function, org-adaptive-fill-paragraph-function), fill-delete-prefix, fill-delete-newlines, canonically-space-region, fill-move-to-break-point, fill-nobreak-p with org's paragraph-start and its three no-break predicates, fill-newline. Elements come from the parser; quote, center and special blocks are parsed into their elements on demand, since the tree keeps blocks opaque.

Tech Stack: Swift 6.2 tools, Swift Testing, Emacs 31.1 / Org 9.8.7 oracle.

Spec: docs/design.md, "Goals" (M-q fill).

Global Constraints

• sentence-end-double-space nil (the user's Doom setting), colon-double-space nil, left-margin 0, left justification, adaptive-fill-mode t.
• fill-column is an option: Emacs's 70 in the oracle's first pass, Doom's 80 in the second and as the app default.
• Src blocks are left alone: Emacs fills them through the language's mode and re-indents them on the way.

Defaults chosen (user may change)

• Fill column 80 (Doom). Mac preset: ⌃⌘P.
• No CJK line breaking rules (kinsoku), no justification with C-u.

---

Task 1: Fill

• Port; oracle over 16 variants (items, comments, quotes, line breaks, timestamps, links, captions, markup at line start, extra spaces) at both fill columns, and over corpus paragraphs (src blocks excluded).
• Commit "Port fill paragraph".

Task 2: App

• M-q / ⌃⌘P; Settings fill column.