Beagle SCM

LITE-032: lite md2mkd — GitHub Markdown normalized to StrictMark

The payoff ticket: a verb that takes any GitHub-flavored .md and writes the same document as StrictMark — 4-char quads, ATX headers, - bullets, one-symbol ref-def labels, single-char emphasis. Parsing is LITE-030's vendored commonmark.js plus LITE-031's GFM extensions; this ticket is the EMITTER that walks the AST and the CLI verb around it. Source bytes are never rewritten by regex: everything is emitted from the tree.

Input

Context

The two CLI forms are gritzko's, verbatim (2026-08-14): lite md2mkd abc.md abc.mkd and lite md2mkd abc. StrictMark's own StrictMark page is the spec for the output; its CommonMark compatibility section is the list of deliberate divergences and therefore the exception list for the verifier.

• Mechanical block mappings: setext → ATX; */+ bullets → -; 1) → 1.; ***/___/--- → ----; > → > ; indented code → a 4-backtick fence; a 3-backtick/tilde fence → 4 backticks, body one quad deeper; every child block one quad (4 spaces) deeper.
• Inline mappings: **x**/__x__ → *x*; an emphasis node → _x_; ~~x~~ → ~x~ (HTML-identical under GFM, where one tilde already strikes); code spans stay verbatim.
• Links: StrictMark has no inline destination form. Every link and image destination is hoisted to a ref def at the foot with a ONE-symbol label (digits, then letters); duplicate URLs collapse onto one label.
• Bare autolinks must be lifted into [text][k] + ref def: left bare they render as links on GitHub and as plain text under StrictMark.
• Escape hazard: a paragraph line matching [A-Z][a-z][a-z0-9]: + gap becomes a META PAIR under StrictMark, so it must be written Note\:.
• Task lists: checked → -[v], unchecked → -[ ]. GFM's [x] NEVER maps to -[x], which means wontfix.

Goals

lite md2mkd converts a real-world README to StrictMark that a StrictMark parser reads as the same document, and that cmark-gfm renders to the same HTML as the input, bar the declared exceptions.

• lite md2mkd <in.md> <out.mkd> — explicit in and out.
• lite md2mkd <stem> — reads <stem>.md, writes <stem>.mkd; a .md suffix on the single argument is accepted and stripped, so md2mkd abc.md writes abc.mkd.
• The verifier: cmark-gfm the input, cmark-gfm the output, diff the HTML. Exceptions are exactly two — the todo quad (GitHub shows -[v] as plain text) and any lifted table. Anything else that diffs is a bug.
• The lint set, reported in plain words, never silently dropped: raw HTML blocks and inlines, tables, footnotes, #####/######, hard line breaks, code spans containing backticks, emphasis nested against StrictMark precedence (an emphasis inside a strong), more than 35 distinct link labels (1..9, a..z), more than 999 list entries.

Constraints

• Verb shape follows lite's: a thin main.js wrapper over an index/md2mkd.js body (see merge/install, LITE-014); the emitter itself is lite/mark/strict.js.
• Refusals and lint go to fd 2 in plain words — no bare codes (CODE, errors in plain words).
• An existing output file is overwritten ONLY when the bytes would not change; otherwise refuse in plain words, so a rerun is safe and a clobber is not.
• Tests are lite's test/md2mkd/run.sh under dash, fixtures under $HOME/tmp, $LITEJAB picks the runtime.
• ZERO quickjab edits.

WIP

Design decisions

• Emission is AST-driven with a depth counter; no source-byte patching anywhere, since nesting is exactly what a regex pass cannot see.
• Ref-def labels are assigned in first-appearance order, 1..9 then a..z; overflow is a lint, not a silent second symbol.
• Tables: OPEN — lift to a transclusion (![table][T]) or keep the GFM table verbatim and accept that StrictMark reads it as paragraph lines. gritzko's call; until then, lint and pass the table through verbatim.

TODOs

• mark/strict.js: the block walk, quads, one continuation law
• the inline walk: precedence, single-char delimiters, code verbatim
• ref-def hoisting, one-symbol labels, autolink lifting
• meta-pair escaping and the rest of the escape hazards
• index/md2mkd.js + main.js wiring: both arg forms, refusals
• test/md2mkd/run.sh: fixtures, the cmark-gfm HTML round-trip, lint legs
• run it over a real README; report

Blockers and bummers

• Open: the table ruling above.
• Two divergences from GitHub's rendering are inherent to StrictMark itself, not emitter bugs, and are NOT in the wiki page's declared list — gritzko's call whether to declare them or revisit the rule:
  1. *strong* (no double symbols) is read as EMPHASIS by CommonMark, so every bold in a converted README renders italic on GitHub, and a second conversion pass degrades it to _x_.
  2. A fence body one quad deeper renders with four extra leading spaces, since CommonMark strips only the opener's indent. Every wiki page with a fenced block already has this.

Outcome

Staged in work/LITE-032, 7 files, nothing posted. Orchestrator verification, run independently of the worker's harness:

• Both arg forms work on ~/src/commonmark.js/README.md (359 lines in, 370 out): md2mkd abc.md abc.mkd and md2mkd abc, rc 0, with the label lint firing in plain words — 2 links past the 35th need a two-symbol label.
• test/md2mkd/run.sh PASS at 76 checks; LITE-030's test/mark/run.sh still PASS at 66.
• The raw cmark-gfm HTML diff on that README is 313 lines, and every one is accounted for by the two divergences above plus the declared table exception — nothing unexplained.
• Converting a StrictMark page (lite/README.mkd) is byte-idempotent on a second pass; its only HTML diff is the fence-indent divergence, on the one block that was indented code rather than a fence.
• Suggested commit message: LITE-032: lite md2mkd, GitHub Markdown to StrictMark