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

Heading Structure Commands 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: Org's heading structure commands, byte- and caret-exact against Emacs: insert heading (M-RET, C-RET, M-S-RET), move subtree (M-up/down), promote/demote subtree (M-S-left/right), heading motion (C-c C-n/p/f/b/u) and set tags (C-c C-q) through a prompt answered in the echo area.

Architecture: Multi-line commands are ported from Org 9.8.7's Lisp onto EmacsBuffer, a whole-text buffer with Emacs's point and marker rules (insert, insert-before-markers, delete-region, replace-match, save-excursion) and org's regexp-based outline primitives. commitBuffer turns the result into one minimal edit and the caret. Motion commands skip headings inside EditContext.hidden (folded text). Prompts go from CommandStep.prompt through OrgEditor.onPrompt to a minibuffer field in the echo area; the answer reruns the command.

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

Spec: docs/design.md, "Commands and keymaps".

Global Constraints

• Org defaults: org-blank-before-new-entry heading auto, org-M-RET-may-split-line t, org-auto-align-tags t, tags column -77.
• The oracle unfolds the buffer after org-mode (#+STARTUP may fold it); cases run with everything visible.
• In plain lists, M-RET and M-S-RET insert items in org; list commands come in the next plan.

Defaults chosen (user may change)

• Mac preset: ⌘↩ insert heading, ⌃⌘↩ after subtree, ⇧⌘↩ TODO heading, ⌃⌥⌘ arrows move/promote/demote subtree, ⌥⌘↑/↓ previous/next heading, ⌃⌘Q tags.
• The tags prompt has no completion yet.

File structure

File	Responsibility
Sources/OrgCore/Commands/EmacsBuffer.swift	Buffer with point and markers, outline primitives, regexps, commitBuffer
Sources/OrgCore/Commands/StructureCommands.swift	Insert, move, promote/demote subtree, motion
Sources/OrgCore/Commands/TagCommands.swift	SetTags
Sources/OrgCore/Commands/Command.swift	EditContext.hidden, Prompt.initial
Sources/OrgEditorAppKit/OrgEditor.swift	Hidden ranges in the context, onPrompt
Sources/Orgstar/*.swift	Prompt in the echo area

---

Task 1: Buffer and structure commands

• Port org-insert-heading (with org--blank-before-heading-p, org-N-empty-lines-before-current), org-insert-todo-heading, org-move-subtree-down, org-promote-subtree/org-demote-subtree (org-map-tree, org-promote, org-demote, org-fix-position-after-promote), org-next-visible-heading, org-forward-heading-same-level, outline-up-heading.
• Oracle: every command at every caret of ten variants (levels, blank lines, tags, text before the first heading, no final newline, non-BMP) and over the corpus (ORGSTAR_ORACLE_CORPUS, files up to 20 KB).
• Commit "Port heading structure commands from org".

Task 2: Tags and prompts

• SetTags: prompt with the current tags, then org-set-tags semantics (realign even when unchanged). Oracle with completing-read-multiple stubbed to the answer.
• Editor onPrompt; app minibuffer field (Return answers, Escape cancels); key bindings in both presets.
• Commit "Set tags through a prompt".