# Blueprint Analysis: CommonMark

## Commander Expectations

- assert the parser reads Markdown from standard input and writes CommonMark-conformant HTML to standard output.

## Crew

| Crew | Charge |
|---|---|
| Commander | Defines intent and decides what done means. |
| Team Lead | Confirms epic completeness and stakeholder expectations. |
| Planning Crew | Authors atomic specifications and the ordered Manifest. |
| Shipyard Crew | Builds the tickets without synchronous Commander access. |

## Story List

### Feature: Parser Interface

| ID | Story | High-level AC |
|---|---|---|
| INTERFACE-001 | Provide the executable standard-input/standard-output interface | An executable `commonmark` accepts UTF-8 Markdown on standard input and writes HTML to standard output. |

### Feature: Block Parsing

| ID | Story | High-level AC |
|---|---|---|
| BLOCK-001 | Parse leaf blocks | The parser handles thematic breaks, ATX and setext headings, indented and fenced code blocks, HTML blocks, paragraphs, and link reference definitions. |
| BLOCK-002 | Parse block quotes | The parser handles block quote markers, nesting, blank lines, lazy continuation, and contained blocks. |
| BLOCK-003 | Parse lists | The parser handles bullet and ordered lists, nesting, continuation, laziness, empty items, tightness, and block content. |

### Feature: Inline Parsing

| ID | Story | High-level AC |
|---|---|---|
| INLINE-001 | Parse escapes, entities, code spans, and line breaks | The parser correctly renders backslash escapes, HTML entities, numeric references, code spans, hard breaks, soft breaks, and literal text. |
| INLINE-002 | Parse emphasis and strong emphasis | The parser applies the CommonMark delimiter-run algorithm, including nesting, intraword rules, delimiter precedence, and unmatched delimiters. |
| INLINE-003 | Parse links and images | The parser handles inline, full, collapsed, and shortcut references, destinations, titles, nested brackets, images, and link restrictions. |
| INLINE-004 | Parse autolinks and raw HTML | The parser handles URI and email autolinks, raw HTML tags, comments, declarations, processing instructions, and CDATA. |

### Feature: Conformance Verification

| ID | Story | High-level AC |
|---|---|---|
| VERIFY-001 | Run the complete conformance suite | `sh sources/full_test.sh` runs unfiltered and exits successfully only when every supplied case passes with zero failures and errors. |

## Surfaced Acceptance Criteria

None.

## Source Inventory

| Path | Content kind | Disposition | Reason |
|---|---|---|---|
| `sources/INSTRUCTIONS.md` | markdown | analyzed | readable UTF-8 |
| `sources/cmark.py` | code | analyzed | readable UTF-8 |
| `sources/full_test.sh` | code | analyzed | readable UTF-8 |
| `sources/normalize.py` | code | analyzed | readable UTF-8 |
| `sources/spec.txt` | text | chunked | split into 18 bounded chunks |
| `sources/spec_tests.py` | code | analyzed | readable UTF-8 |

## Relationship Model

| Source or group | Relationship type | Related source or group | Evidence | Delivery implication |
|---|---|---|---|---|
| `sources/spec.txt` | normative specification and conformance test suite | `sources/spec_tests.py` | The test runner extracts examples and expected HTML from the specification. | Stories must follow the specification sections and use section-scoped checks. |
| `sources/spec_tests.py` | test-kit-to-implementation | `commonmark` | `spec_tests.py` invokes the supplied program through `cmark.py`. | The executable interface must remain stable. |
| `sources/cmark.py` | test helper | `commonmark` | `CMark(prog=...)` pipes UTF-8 input to the program and captures output. | Stage the helper and preserve standard streams. |
| `sources/normalize.py` | test helper | `sources/spec_tests.py` | The runner normalizes HTML before comparison. | Stage the normalizer with the harness. |
| `sources/full_test.sh` | instruction-to-test | `sources/spec_tests.py` | The supplied script invokes the unfiltered suite and checks the clean tally. | The terminal verification story is the only full-suite story. |
| `sources/INSTRUCTIONS.md` | author intent | all implementation stories | It defines implementation order, prohibitions, interface, and acceptance structure. | Use as planning context; do not stage it. |

## Source Roles

| Path | Role | Plan disposition | Build disposition |
|---|---|---|---|
| `sources/INSTRUCTIONS.md` | author intent | compass | prompt-only |
| `sources/spec.txt` | normative specification and conformance test suite | context | stage |
| `sources/spec_tests.py` | conformance harness | context | stage |
| `sources/cmark.py` | test helper | context | stage |
| `sources/normalize.py` | test helper | context | stage |
| `sources/full_test.sh` | conformance harness | context | stage |

## Planning Instructions

### Delivery Shape

The system is a command-line Markdown parser. It accepts UTF-8 Markdown through standard input, constructs block structure, parses inline content, and emits HTML through standard output. Delivery proceeds from the executable interface to block parsing, then inline parsing, followed by scoped specification checks and one terminal unfiltered conformance run.

### Story Realization Map

| Story ID | Blueprint scope | Evidence | Related files | Delivery type |
|---|---|---|---|---|
| INTERFACE-001 | Executable process boundary and UTF-8 streams | `sources/INSTRUCTIONS.md`, `sources/cmark.py` | `sources/cmark.py` | capability |
| BLOCK-001 | Leaf blocks and reference definitions | `sources/spec.txt` sections `Leaf blocks`, `Paragraphs`, `Link reference definitions` | `sources/spec_tests.py`, `sources/normalize.py` | capability and scoped harness |
| BLOCK-002 | Block quotes | `sources/spec.txt` section `Block quotes` | `sources/spec_tests.py` | capability and scoped harness |
| BLOCK-003 | Lists and tightness | `sources/spec.txt` sections `List items`, `Lists` | `sources/spec_tests.py` | capability and scoped harness |
| INLINE-001 | Escapes, entities, code spans, hard and soft breaks, textual content | `sources/spec.txt` sections `Backslash escapes`, `Entity and numeric character references`, `Code spans`, `Hard line breaks`, `Soft line breaks` | `sources/spec_tests.py` | capability and scoped harness |
| INLINE-002 | Emphasis and strong emphasis | `sources/spec.txt` section `Emphasis and strong emphasis` | `sources/spec_tests.py` | capability and scoped harness |
| INLINE-003 | Links and images | `sources/spec.txt` sections `Links`, `Images` | `sources/spec_tests.py` | capability and scoped harness |
| INLINE-004 | Autolinks and raw HTML | `sources/spec.txt` sections `Autolinks`, `Raw HTML` | `sources/spec_tests.py` | capability and scoped harness |
| VERIFY-001 | Complete supplied suite execution | `sources/full_test.sh` | all staged runtime assets and `commonmark` | acceptance contract |

### Test and Acceptance Strategy

Implementation stories use `spec_tests.py` with explicit section selectors covering only their owned sections and declare `Suite: scoped`. The terminal verification story depends on every implementation story, declares `Suite: full`, and runs `sh sources/full_test.sh`. The supplied harness and its imported helpers are staged unchanged.

### Sequencing and Dependencies

Build the executable interface first. Implement block parsing before inline parsing, with reference definitions available before inline rendering. Stage `spec.txt`, `spec_tests.py`, `cmark.py`, `normalize.py`, and `full_test.sh` before verification. Run scoped checks after each relevant parser capability; run the complete suite only in `VERIFY-001`.

### Source Conflicts and Gaps

No conflicting product definitions were found. The sources do not specify a framework, persistence layer, deployment platform, authentication model, or interactive UI; these are not required for the described local CLI. The source does prohibit use of a public Markdown implementation and modification of supplied conformance assets.

## Analysis Notes
generated: 2026-08-15
blueprint: /mnt/c/Users/barlo/projects/drydock/uat/Commonmark/runs/20260815.202344/workspace/targets/commonmark/blueprint

Quality: Questions
  blockers: 0
  questions: 1
  features: 4
  stories: 9
  stack: Python 3 and POSIX shell
  display_name: CommonMark
  short_description: A command-line CommonMark 0.31.2 parser that converts Markdown from standard input to HTML on standard output.

The identity questionnaire remains open because the project display name and short description were blank. No other human-owned planning decisions are required.