Org-Mode Rejection Rationale (ADR-021)
This page is the durable rationale record behind
ADR-021: Org-Mode Is Rejected as a Project Format
(Accepted, session 244, user-ratified after adversarial review). The full
investigation is reports/research-org-mode.md in the
orchestrata-ultimate-architecture repo (dated 2026-07-18); this page preserves
its findings where the RAG stack can retrieve them — the RAG evaluation found
the rationale previously lived only in the repo's reports/, invisible to wiki
recall.
The question
Should orchestrata-ultimate adopt Emacs org-mode for specs, docs, runbooks, or literate programming? Method: web research on the July-2026 library/tooling state plus an audit of the repo's existing documentation conventions. No code was changed during the evaluation.
Verdict: REJECT
Every rendering and tooling surface the project depends on is markdown-native
— Wiki.js (markdown-only, Mermaid 8.8.2), GitLab (org rendered read-only via
the dormant org-ruby gem, which drops Mermaid), 512 markdown files under
specs/ + docs/ + plans/ with 130 working ```mermaid fences, five
markdown-parsing pipeline scripts, and the LLM agents themselves — while the
Python org ecosystem is hobby-grade and read-mostly. Org-mode would add an
Emacs toolchain dependency to buy features the repo already has via the
session CLI, the Neo4j KG, @traces, and scripts/.
Baseline at evaluation time: 0 real .org files in the repo, 70 spec
directories all in markdown.
Scorecard
The bar for each area was "at least as good as what the repo does today":
| Area | Verdict | Decisive fact |
|---|---|---|
| Org AST parser alongside the AST toolkit | FAIL | No Python parser does full-element AST + round-trip serialization; the only complete org parser is Emacs itself (org-element.el in batch mode). orgparse is read-only; orgmunge treats body content as an opaque blob; tree-sitter-org is a highlighting-grade CST from a fork of a grammar dormant since 2023-06. |
| Mermaid embedding/rendering | FAIL | Breaks 2 of 3 render targets: Wiki.js has no org format at all; GitLab's org-ruby renders Mermaid blocks as dead code. ob-mermaid replaces live-rendered text with an Emacs + Node + Chromium compile-to-image step. |
| Babel tangle/detangle for literate specs/runbooks | FAIL (specs) / MARGINAL (runbooks) | Tangle requires batch Emacs in CI; detangle depends on comment markers and breaks under multi-agent direct-file editing plus the black/ruff auto-format hook. Specs are already machine-executed via the markdown toolchain (parse_spec_requirements.py → Prolog facts, generate_rtm_evidence.py → RTM). |
| Other org features (TODO/agenda, drawers, radio targets) | FAIL | Each duplicates a wired, tested system: session CLI backlog + SPEC-023 goals + Todoist; Neo4j KG metadata; markdown links + @traces + RTM. Adopting org would create a second task source of truth invisible to session-CLI validation and the KG. |
| Downsides | Confirmed heavy | Full org fidelity exists only in Emacs (VS Code support self-describes "In Progress"); LLM agents are markdown-trained; the tooling rewrite blast radius covers at least six pipeline scripts plus the wiki sync workflow and two volk tools. |
Decision flow:
What was kept instead
Markdown plus the existing machinery remain the project formats:
- Specs/docs/plans — markdown, parsed by
parse_spec_requirements.py,generate_rtm_evidence.py,spec_word_cloud.py,gen_level0.py,gen_codebase_map.py. - Diagrams —
```mermaidfences, live-rendered by GitLab, Wiki.js (8.8.2), and artifacts; gated by thevalidate_mermaidvolk tool. - Task/TODO tracking — the session CLI backlog, SPEC-023 goals, and the Todoist integration.
- Metadata and traceability — the Neo4j knowledge graph and
@tracesrequirement↔code↔test joins. - Executable runbooks —
scripts/*.py+ agent skills; if session-persistent executable notebooks ever become a real need, the ruled fallback is Jupyter/ipynb, not org.
No pilot was recommended: the failures rest on ecosystem facts a pilot cannot change (Wiki.js has no org renderer; the Python parsers lack element-level round-trip).
Consequences
ADR-021 is the fourth ratification of reuse-over-invention (after SPEC-104 OpenSpec, SPEC-105 OWL/SHACL, and the no-new-DSL ruling). Any future format proposal must displace the ADR explicitly. See the decisions page for the canonical record.