COMPASS: CommonMark

Compass

CommonMark is a command-line Markdown parser for users and automation that converts CommonMark 0.31.2 input into HTML. The parser reads standard input, writes standard output, and is judged by the supplied complete conformance suite.

Constraints

• Implement the supplied CommonMark 0.31.2 behavior.
• Parse block structure before inline structure.
• Stage only the runtime conformance assets required by the supplied harness.
• Keep focused verification bounded to the story-owned selectors.
• Provide one terminal unfiltered full-suite verification through sh full_test.sh.

Guardrails

• Do not use a public Markdown implementation.
• Preserve the harness's standard-input, standard-output, and exit-status contract.
• Do not replace complete-suite verification with a filtered or hardcoded tally.
• Do not treat imported instructions as runtime application assets.

<!-- drydock:build-write-guardrail:start -->

Build Write Guardrail

• Authorized build directory: /mnt/c/Users/barlo/projects/drydock/uat/CommonMark/runs/20260812.171514/build/commonmark
• Authorized Target directory: /mnt/c/Users/barlo/projects/drydock/uat/CommonMark/runs/20260812.171514/workspace/targets/commonmark
• Build agents have permission to create, modify, and remove files required by the active build block inside these authorized directories.
• No path outside these authorized directories may be modified.
• Protected Drydock artifacts:
  • /mnt/c/Users/barlo/projects/drydock/uat/CommonMark/runs/20260812.171514/workspace/targets/commonmark/blueprint/
  • /mnt/c/Users/barlo/projects/drydock/uat/CommonMark/runs/20260812.171514/workspace/targets/commonmark/MANIFEST.md
  • /mnt/c/Users/barlo/projects/drydock/uat/CommonMark/runs/20260812.171514/workspace/targets/commonmark/COMPASS.md
  • /mnt/c/Users/barlo/projects/drydock/uat/CommonMark/runs/20260812.171514/workspace/targets/commonmark/QuarterDeck/
  • /mnt/c/Users/barlo/projects/drydock/uat/CommonMark/runs/20260812.171514/workspace/targets/commonmark/evidence/

<!-- drydock:build-write-guardrail:end -->

<!-- Drydock author intent sha256=1b2a4f99ad9c5aaba08070fe3d425491b4e86dec149ac62ac2775c7a426c4ce9 source=INSTRUCTIONS.md -->

Build Instructions: CommonMark Parser

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

The sole definition of product success is sh full_test.sh returning exit code 0. full_test.sh runs the complete, unfiltered supplied CommonMark suite. Treat the suite runner's exit status as the verdict; do not parse or hardcode its printed tally.

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, and normalize.py.

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

Do not create acceptance checks asserting that imported or staged files merely exist. Do not create a scoped check by invoking full_test.sh; it is intentionally full-suite only. Parser implementation stories may run the supplied harness with explicit section selectors that cover the whole story scope.

A section selector must select examples. spec.txt nests example-bearing headings such as ATX headings and List items under chapter titles such as Leaf blocks, Container blocks, and Characters and lines; the chapter titles own no examples of their own, so a selector naming one matches nothing, exits zero, and proves nothing. Select on the headings that own examples, and cover a chapter by naming all of them.

The final verification story depends on all parser stories, creates full_test.sh, and has exactly one terminal Suite: full acceptance check. The check prints captured standard output and standard error and asserts only result.returncode == 0. It carries Sea Trials: st-001.

Do not add separate verification stories for script presence, focused verification, staged assets, or complete verification.

Deliver a concise project README.md documenting the standard-input/standard-output interface and the sh full_test.sh command.