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

 1# Babel Implementation Plan
 2
 3> **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.
 4
 5**Goal:** C-c C-c in a src block runs it (sh and the other shells, python, emacs-lisp, and ruby/js/R/awk for output) and writes `#+RESULTS:` as Emacs does.
 6
 7**Architecture:** `OrgCore/Compute/Babel.swift` plans and finishes; the platform runs. `Babel.plan` resolves header arguments as `org-babel-merge-params` does (defaults, `header-args` properties from the file and headings, the block line, `#+HEADER:` lines; `:results` by exclusive groups; `:var` by name), refuses `:eval never`, `:session`, `:noweb`, `:file`, `:prologue`, `:epilogue`, `:post`, `:stdin`, `:cmdline`, `:shebang`, `:cache yes` and src-block references with a message, and builds a `BabelJob`: the program on standard input for the interpreter (shell variables as `name='value'`, python wrapped in `def main()` with a result file as ob-python does, emacs-lisp evaluated in `emacs --batch` printing its value as JSON). `Babel.finish` applies `org-babel-result-cond`, the table import (`org-table-convert-region` with `babel-auto`, `org-babel--string-to-number`), python's `table-or-string`, and `org-babel-insert-result`: where the results go (`#+RESULTS:` after the block or `#+RESULTS: name`), `replace`/`append`/`silent`, tables aligned, lists, `raw`, `drawer`, `code`, `org`, `html`, `latex`, `:wrap`, `: ` lines under ten lines and example blocks from ten, code escaping, indentation. The app asks before running (yes/no/always, trusted by block content in `trusted.json`; `:eval query` always asks), runs the job with `BabelRunner`, and writes the result if the block is still there.
 8
 9**Tech Stack:** Swift 6.2 tools, Swift Testing, Emacs 31.1 / Org 9.8.7 oracle with python3.
10
11**Spec:** `docs/design.md`, "Babel execution (macOS)".
12
13## Global Constraints
14
15- Oracle: 53 blocks run natively and by `org-babel-execute-src-block`; whole buffers compared.
16- Shell blocks run `sh`, `bash`, … by name with the program on standard input; `shell` runs `/bin/sh`.
17- The python wrapper is written for Orgstar and behaves as ob-python's (no pandas or numpy conversion).
18
19## Defaults chosen (user may change)
20
21- `python3` for python blocks (`:python` overrides); five-minute timeout.
22- `:var` tables with rules, `name[...]` indexing, calls and src-block references aren't supported yet; tables and lists only for python and emacs-lisp.
23
24---
25
26- [x] `Babel.plan`, `Babel.finish`, `ExecuteSrcBlock`, `src` key context, `C-c C-c`; oracle.
27- [x] `BabelRunner`, `DocumentSession.runBabel`, confirmation and trust; session test.
28- [x] Commit "Babel".