adf-codec/todo.md

Todo

The plan, in order. Nothing is built. Design questions are settled in AGENTS.md; remaining spec detail is settled at its own milestone.

Milestones

• 0 — Scaffold. package.json per §6, tsconfig.json, .npmrc (save-exact=true), the Docker tooling, renovate.json (§9), and .gitea/workflows/ci.yml gating branches: runs-on: docker-host, actions pinned to semver tags.
• 1 — The flavour spec. The markdown flavour written as this repo's specification before any implementation: the directive grammar (attributes, escaping, nesting), each node's syntax from the inventory below, the opaque-carry spelling, the pipe-vs-directive table rule, and what CommonMark's raw-HTML constructs become in ADF, which has no raw-HTML node — likely the §3 element mapping, error otherwise. Start the corpus (§10) from this spec.
• 2 — adfToMarkdown.
• 3 — markdownToAdf. The CommonMark parser is the largest single component.
• 4 — Round-trip property tests over the corpus, both ways — the thing that proves 2 and 3.
• 5 — Release pipeline, ship 0.1.0. Publish-on-version-change (§9), NPM_TOKEN secret, the repo made public first (§6). 0.1.0 is the markdown round-trip: both markdown directions, the types, isAdfDocument. The maintainer's bump PR also removes private: true, the guard against any earlier publish.
• 6 — The HTML dialect spec. Element-by-element mapping, the data-* fidelity scheme, the opaque-carry form, and the documented foreign-element set htmlToAdf accepts.
• 7 — HTML, ship 0.2.0. adfToHtml, htmlToAdf, the composed markdownToHtml / htmlToMarkdown. CommonMark spec suite runs against markdownToHtml from here (§10).
• 8 — CLI. A later goal, shaped around the personas once the library exists.

The ADF inventory to cover

From Atlassian's structure reference — not the whole schema: real payloads also carry taskList/taskItem, decisionList/decisionItem, layoutSection/layoutColumn, blockCard/embedCard, extension/bodiedExtension/inlineExtension and placeholder, none documented there. The documented set is the floor: the floor gets designed syntax, the rest rides the opaque carry (§3) until it does too.

Top-level block	blockquote bodiedSyncBlock bulletList codeBlock expand heading mediaGroup mediaSingle multiBodiedExtension orderedList panel paragraph rule syncBlock table
Child block	blockTaskItem extensionFrame listItem media nestedExpand tableCell tableHeader tableRow
Inline	date emoji hardBreak inlineCard mediaInline mention status text
Marks	border code em link strike strong subsup textColor underline

Plain markdown covers blockquote, bulletList, codeBlock, heading, orderedList, paragraph, rule, listItem, hardBreak, text, and the code, em, link, strike and strong marks. Everything else is what the flavour is for.