=== ANALYSIS.md ===
# Blueprint Analysis: CommonMark
## Commander Expectations
- assert the parser reads CommonMark from standard input, writes HTML to standard output, and passes the complete supplied conformance suite.
## 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: Command-Line Parser
| ID | Story | High-level AC |
|---|---|---|
| CLI-001 | Implement standard-input and standard-output entry point | The executable reads UTF-8 Markdown from stdin and writes rendered HTML to stdout. |
| CLI-002 | Implement parser error and process behavior | Invalid operational conditions produce deterministic diagnostics and nonzero exit behavior without corrupting stdout. |
| CLI-003 | Document parser operation | README.md documents the stdin/stdout interface and `sh full_test.sh`. |
### Feature: Block Structure
| ID | Story | High-level AC |
|---|---|---|
| BLOCK-001 | Parse leaf blocks | The parser handles thematic breaks, ATX and setext headings, indented code, fenced code, 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 block structure. |
| BLOCK-003 | Parse list items and list structure | The parser handles bullet and ordered lists, nesting, lazy continuation, empty items, indentation, delimiter changes, and tight versus loose rendering. |
### Feature: Inline Parsing
| ID | Story | High-level AC |
|---|---|---|
| INLINE-001 | Parse escapes and character references | The parser handles punctuation escapes, entity references, numeric references, replacement characters, and context restrictions. |
| INLINE-002 | Parse code spans and line breaks | The parser handles code span delimiter lengths, normalization, hard breaks, and soft breaks. |
| INLINE-003 | Parse emphasis and strong emphasis | The parser applies delimiter-run rules, nesting, intraword restrictions, and precedence. |
| INLINE-004 | Parse links and images | The parser handles inline, full, collapsed, and shortcut references plus nested image descriptions and destination/title rules. |
| INLINE-005 | Parse autolinks and raw HTML | The parser handles URI/email autolinks, HTML tags, comments, declarations, processing instructions, and CDATA. |
### Feature: HTML Rendering
| ID | Story | High-level AC |
|---|---|---|
| RENDER-001 | Render block structure as HTML | Parsed blocks render with the required CommonMark HTML elements, nesting, escaping, and list paragraph rules. |
| RENDER-002 | Render inline structure as HTML | Inline nodes render with required escaping, links, images, code, emphasis, breaks, and raw HTML preservation. |
| RENDER-003 | Normalize URL, title, and attribute output | Rendered URLs, titles, attributes, and special characters match the supplied harness expectations. |
### Feature: Conformance Verification
| ID | Story | High-level AC |
|---|---|---|
| VERIFY-001 | Stage the supplied conformance assets | `spec.txt`, `spec_tests.py`, `cmark.py`, and `normalize.py` are available at their required runtime paths. |
| VERIFY-002 | Add bounded story verification | Parser stories run only their selected conformance sections or examples and report failures deterministically. |
| VERIFY-003 | Run the complete conformance suite | The terminal verification story runs `sh full_test.sh`, declares `Suite: full`, and passes the Sea Trial when the command exits zero. |
## Surfaced Acceptance Criteria
| ID | Story ID | Criterion |
|---|---|---|
| AC-001 | CLI-001 | The parser consumes Markdown from standard input and emits HTML to standard output. |
| AC-002 | VERIFY-001 | Runtime conformance assets include the supplied harness and every module it imports. |
| AC-003 | VERIFY-003 | The complete unfiltered supplied suite is executed as the final verification gate. |
| AC-004 | CLI-003 | README.md remains concise and documents the required invocation. |
## Relationship Model
| Source or group | Relationship type | Related source or group | Evidence | Delivery implication |
|---|---|---|---|---|
| `sources/INSTRUCTIONS.md` | instruction-to-test | `sources/spec_tests.py` | Defines full-suite policy, scoped selectors, staging, and README requirements. | Planning must preserve bounded story checks and one terminal full-suite story. |
| `sources/spec.txt` | normative specification and conformance test suite | `sources/spec_tests.py` | The harness parses examples from `spec.txt`. | Stage the specification and use section selectors for focused verification. |
| `sources/spec_tests.py` | test-kit-to-implementation | parser executable | `CMark` invokes the deliverable and compares normalized HTML. | The executable must support stdin/stdout operation and deterministic exit codes. |
| `sources/spec_tests.py` | test-kit-to-helper | `sources/cmark.py`, `sources/normalize.py` | The harness imports both modules. | Stage both helper modules with the harness. |
| `sources/cmark.py` | implementation-to-helper | parser executable | Provides subprocess invocation of the tested program. | Conformance verification must invoke the real deliverable entry point. |
| `sources/normalize.py` | parser-to-normalizer | rendered HTML | Normalizes insignificant HTML differences before comparison. | Rendering must preserve all significant HTML semantics. |
## 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 |
## Planning Instructions
### Delivery Shape
The system is a command-line CommonMark 0.31.2 parser. It accepts Markdown on stdin, performs block parsing followed by inline parsing, renders HTML on stdout, and is verified by the supplied Python conformance harness and shell wrapper.
### Story Realization Map
| Story ID | Durable Blueprint scope | Evidence | Related files | Delivery kind |
|---|---|---|---|---|
| CLI-001 | Executable interface | `sources/INSTRUCTIONS.md` | `sources/spec_tests.py`, `sources/cmark.py` | capability |
| CLI-002 | Process and failure behavior | `sources/INSTRUCTIONS.md` | `sources/spec_tests.py` | capability and acceptance |
| CLI-003 | Operator documentation | `sources/INSTRUCTIONS.md` | README.md | documentation |
| BLOCK-001 | Leaf block parser | `sources/spec.txt` | `sources/spec_tests.py` | capability |
| BLOCK-002 | Block quote parser | `sources/spec.txt` | `sources/spec_tests.py` | capability |
| BLOCK-003 | List parser | `sources/spec.txt` | `sources/spec_tests.py` | capability |
| INLINE-001 | Escapes and references | `sources/spec.txt` | `sources/spec_tests.py` | capability |
| INLINE-002 | Code spans and breaks | `sources/spec.txt` | `sources/spec_tests.py` | capability |
| INLINE-003 | Emphasis algorithm | `sources/spec.txt` | `sources/spec_tests.py` | capability |
| INLINE-004 | Links and images | `sources/spec.txt` | `sources/spec_tests.py` | capability |
| INLINE-005 | Autolinks and HTML | `sources/spec.txt` | `sources/spec_tests.py` | capability |
| RENDER-001 | Block HTML renderer | `sources/spec.txt` | `sources/normalize.py` | capability |
| RENDER-002 | Inline HTML renderer | `sources/spec.txt` | `sources/normalize.py` | capability |
| RENDER-003 | Output normalization compatibility | `sources/spec.txt`, `sources/normalize.py` | `sources/spec_tests.py` | integration |
| VERIFY-001 | Runtime conformance assets | `sources/INSTRUCTIONS.md`, `sources/spec_tests.py` | all staged source assets | integration |
| VERIFY-002 | Scoped story checks | `sources/INSTRUCTIONS.md`, `sources/spec_tests.py` | selected harness invocations | test harness |
| VERIFY-003 | Full-suite terminal gate | `sources/INSTRUCTIONS.md`, `SEA_TRIALS.md` | `full_test.sh` | acceptance contract |
### Test and Acceptance Strategy
Block and inline stories use focused selectors matching example-bearing headings in `spec.txt`. Rendering stories use bounded harness runs covering their owned syntax. No story other than VERIFY-003 runs the complete suite. VERIFY-003 is the sole terminal verification story, depends on every implementation story, declares `Suite: full`, and proves Sea Trial `st-001` through the exit status of `sh full_test.sh`.
### Sequencing and Dependencies
The executable interface precedes harness integration. Block parsing precedes inline parsing; list parsing depends on the shared block model. Rendering depends on both parser phases. The conformance assets are staged before focused verification. The full-suite story follows all parser and rendering stories and creates or invokes `full_test.sh`.
### Source Conflicts and Gaps
No conflicting product definitions were found. The implementation language and deployment packaging are not specified; the proposed stack records conventional choices without blocking planning. Authentication, persistence, external services, and UI workflows are not applicable to the described CLI parser.
## Analysis Notes
generated: 2026-08-12
blueprint: /mnt/c/Users/barlo/projects/drydock/uat/CommonMark/runs/20260812.171514/workspace/targets/commonmark/blueprint
Quality: Questions
blockers: 0
questions: 1
features: 5
stories: 16
stack: Python 3 and POSIX shell; no application framework
display_name: CommonMark
short_description: A command-line CommonMark 0.31.2 parser that converts standard-input Markdown to HTML on standard output.
None.
=== END ANALYSIS.md ===
=== SEA_TRIALS.md ===
# Sea Trials: CommonMark
## st-001: The complete conformance suite passes
Type: technical
Required: yes
Criterion: The parser shall pass every test run by `sh full_test.sh`.
Verification: proof
Pattern: ubiquitous
Command: ["sh", "full_test.sh"]
## st-002: The parser uses the required command-line interface
Type: technical
Required: yes
Criterion: The parser shall read Markdown from standard input and write HTML to standard output.
Verification: proof
Pattern: ubiquitous
## st-003: The supplied conformance assets are available at runtime
Type: technical
Required: yes
Criterion: The build shall stage `spec.txt`, `spec_tests.py`, `cmark.py`, and `normalize.py` with their required runtime imports.
Verification: proof
Pattern: ubiquitous
## st-004: The parser does not use a public Markdown implementation
Type: guardrail
Required: yes
Criterion: The parser shall not use a public Markdown implementation.
Verification: evidence
Pattern: ubiquitous
## Questions
- None.
=== END SEA_TRIALS.md ===
=== TECHNOLOGY_STACK.md ===
# Technology Stack
| Technology | Rigging | Notes |
|---|---|---|
| Python 3 | `python.md` | Used by the supplied conformance harness; conventional implementation language for the parser. |
| POSIX shell | `common.md` | Required for `sh full_test.sh`. |
| Python standard library | `python.md` | Prefer standard-library facilities; no application framework is specified. |
| HTML | — | Required output format for rendered Markdown. |
=== END TECHNOLOGY_STACK.md ===
=== COMPASS.md ===
# 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.
=== END COMPASS.md ===
=== discovery-identity.json ===
{
"id": "discovery-identity",
"title": "Discovery: Project Identity",
"purpose": "Confirm the proposed display name and short description before planning.",
"questions": [
{
"id": "display_name",
"label": "Display Name",
"prompt": "The display name Drydock will use for this project. Edit to override the proposal.",
"input": "text",
"proposed": "CommonMark",
"answer": "CommonMark"
},
{
"id": "short_description",
"label": "Short Description",
"prompt": "One-sentence description of what this project does. Edit to override the proposal.",
"input": "textarea",
"proposed": "A command-line CommonMark 0.31.2 parser that converts standard-input Markdown to HTML on standard output.",
"answer": "A command-line CommonMark 0.31.2 parser that converts standard-input Markdown to HTML on standard output."
}
]
}
=== END discovery-identity.json ===Run artifact