Build Instructions: CommonMark Parser

Build a CommonMark 0.31.2 parser from the supplied specification. The parser reads Markdown from standard input and writes HTML to standard output. Do not use a public Markdown implementation.

The deliverable is an executable named commonmark at the application root.

sources/INSTRUCTIONS.md is imported specification prose. It is not staged into the completed application. The runtime conformance assets are only spec.txt, spec_tests.py, cmark.py, normalize.py, and full_test.sh.

Run Harness

sources/full_test.sh is the single scoring entry point. It is supplied, not authored: it is staged verbatim into the build directory alongside the other imported assets, and drydock uat runs sh sources/full_test.sh from the completed application root and takes its exit code and output as the score. It runs the complete, unfiltered supplied CommonMark suite against ./commonmark.

The interface check is deliberately separate from the conformance run so that a missing executable and a genuine conformance failure are distinguishable in the evidence.

The scoring assets are read-only. sources/full_test.sh, sources/spec_tests.py, sources/cmark.py, sources/normalize.py, and sources/spec.txt are hash-verified against the import and restored before grading, so a modification is reported as tampering rather than honored. Do not write to them. Build ./commonmark so that the supplied entry point succeeds; changing the entry point is not a repair.

Create a concise project README.md describing the standard-input/standard-output interface. README content is not an acceptance criterion and does not require a documentation story.

Implementation Guidance

CommonMark parsing is two phases: resolve block structure first, then run inline parsing over the block contents. Implement in that order.

1. Blocks: paragraphs, thematic breaks, ATX headings, setext headings, indented code, fenced

code, HTML blocks, link reference definitions, block quotes, then lists — lists are the hardest block construct, with lazy continuation, nesting, and tightness.

1. Inlines: backslash escapes, entity and numeric references, code spans, emphasis and strong

emphasis (the delimiter-run algorithm), links and images, autolinks, raw HTML, hard breaks.

The specification text is normative and contains the algorithms. The "Appendix: A parsing strategy" section describes the reference implementation's approach; follow it directly rather than reinventing the rules.

Acceptance

Parser implementation stories may run spec_tests.py with explicit section selectors covering the story's complete scope. A selector must name headings that own examples, such as ATX headings or List items. Chapter headings such as Leaf blocks, Container blocks, and Characters and lines own no examples; selecting them can exit zero without testing anything.

Create one terminal verification story that:

• depends on every parser implementation story;
• contains the only Suite: full acceptance check;
• runs sh sources/full_test.sh, prints captured standard output and standard error, and asserts

only result.returncode == 0; and

• carries Sea Trials: st-001.

Do not author full_test.sh; it is supplied. Do not invoke it from scoped checks. Do not create file-presence or staged-asset acceptance checks, or additional verification stories.