docs(adr): ADR-0001 content engine — demote Pandoc, Djot prose / a2ml typed, boj substrate#42
Merged
Merged
Conversation
… typed, boj substrate Proposed decision record. Demote Pandoc to an authoring-time importer; adopt Djot (jotdown now, verified Zig/Idris2 Djot core later) as the canonical prose syntax; keep a2ml as the typed-data face; ship casket as a boj capability cartridge consuming boj's verified MCP/ABI/distribution/credential-isolation rather than building its own; layered proof boundary (Haskell cheap invariants, Idris2/Agda load-bearing, FlexiText as echo-types Echo). Includes sequencing discipline: ship cheap differentiators first, demote Pandoc underneath once the core is proven. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WN6nPWWe4dvXfoqBG6auWN
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
hyperpolymath
marked this pull request as ready for review
June 23, 2026 20:22
7 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
ADR-0001 (Proposed) — content engine direction
Decision record capturing the Pandoc-demotion pivot, folding in the boj substrate and Djot conclusions from discussion. Proposed status — for ratification/reshaping, not silent landing.
The decision in one breath: demote Pandoc to an authoring-time importer; adopt Djot as the canonical prose syntax (
jotdownRust parser now → verified Zig/Idris2 Djot core later, behind a stable AST); keep a2ml as the typed-data face (Djot replaces CommonMark, not a2ml); ship casket as a boj capability cartridge that consumes boj's verified MCP surface / Idris2 ABI / distribution / credential isolation instead of building its own (Emanote-style); and a layered proof boundary (Haskell cheap invariants, Idris2/Agda load-bearing,FlexiTextas anecho-typesEcho).Why Djot is the keystone: it shrinks the verifiable-parser target from impossible (CommonMark) to finishable (Djot, by the CommonMark/Pandoc author), reuses
jotdownso we ship now, and its native attributes/divs/spans turn casket's a11y from string-rewrite hacks into first-class syntax.Sequencing discipline (load-bearing): ship the cheap differentiators first on today's engine (README truthing, register as a boj cartridge,
llms.txt/per-page views offdescriptiles/, wireSixSCM→descriptiles/*.a2ml) and demote Pandoc underneath them once the Djot/Idris2 core is proven — never gate the perishable agent-native window on the slow rewrite.Scope note: this is a decision doc only — no code/engine change in this PR. The first cheap slice (README truthing) follows as a separate PR.
🤖 Generated with Claude Code
https://claude.ai/code/session_01WN6nPWWe4dvXfoqBG6auWN
Generated by Claude Code