=== TOPOLOGY.md ===
planning_feedback: |
analyze-display_name applied ARCHITECTURE.md
analyze-short_description applied ARCHITECTURE.md
## story architecture
summary: Define parser architecture and module boundaries.
type: foundational
kind: capability
phase: 1
implements: ARCHITECTURE.md
stack: common.md, python.md
provides: parser architecture, block parser boundary, inline parser boundary, renderer boundary
acceptance: yes
scope: both
instructions: |
Define the Python module boundaries for a two-phase CommonMark parser, HTML renderer, executable entry point, and POSIX conformance wrapper. Record the approved technology stack and prohibit public Markdown implementations.
## story cli-entrypoint
summary: Implement the standard-input and standard-output parser entry point.
type: service
kind: capability
phase: 1
implements: FEATURE-CLI-ENTRYPOINT.md
covers: CLI-001
context: sources/cmark.py, sources/normalize.py
context_roles: |
cmark.py: test helper
normalize.py: test helper
stack: common.md, python.md
provides: parser executable
consumes: parser core, HTML renderer
depends: architecture
acceptance: yes
scope: target
instructions: |
Implement the executable that reads UTF-8 Markdown from standard input, parses blocks before inlines, and writes rendered HTML to standard output. Preserve the harness invocation contract.
## story cli-errors
summary: Define deterministic parser process errors and exit behavior.
type: service
kind: capability
phase: 1
implements: FEATURE-CLI-ERRORS.md
covers: CLI-002
context: sources/spec_tests.py
context_roles: |
spec_tests.py: conformance harness
stack: common.md, python.md
provides: parser error behavior
consumes: parser executable
depends: cli-entrypoint
acceptance: yes
scope: target
instructions: |
Implement deterministic operational failure handling, nonzero exit behavior, and stdout integrity for invalid process conditions. Keep diagnostics on stderr.
## story cli-documentation
summary: Document parser operation and conformance verification.
type: service
kind: documentation
phase: 1
implements: FEATURE-CLI-DOCUMENTATION.md
covers: CLI-003
stack: common.md
depends: cli-entrypoint
acceptance: yes
scope: target
instructions: |
Write a concise README documenting standard-input to standard-output operation and the required sh full_test.sh invocation.
## story block-leaf
summary: Parse CommonMark leaf blocks.
type: service
kind: capability
phase: 2
implements: FEATURE-BLOCK-LEAF.md
covers: BLOCK-001
context: sources/spec.txt, sources/spec_tests.py
context_roles: |
spec.txt: normative specification and conformance test suite
spec_tests.py: conformance harness
stack: common.md, python.md
provides: leaf block parser
consumes: parser executable
depends: cli-entrypoint
acceptance: yes
scope: target
instructions: |
Implement thematic breaks, ATX and setext headings, indented and fenced code blocks, HTML blocks, paragraphs, and link reference definitions according to CommonMark 0.31.2.
## story block-quotes
summary: Parse nested block quotes and lazy continuation.
type: service
kind: capability
phase: 2
implements: FEATURE-BLOCK-QUOTES.md
covers: BLOCK-002
context: sources/spec.txt, sources/spec_tests.py
context_roles: |
spec.txt: normative specification and conformance test suite
spec_tests.py: conformance harness
stack: common.md, python.md
provides: block quote parser
consumes: leaf block parser
depends: block-leaf
acceptance: yes
scope: target
instructions: |
Implement block quote markers, nesting, blank lines, lazy paragraph continuation, and all contained block structure.
## story block-lists
summary: Parse CommonMark list items and list structure.
type: service
kind: capability
phase: 2
implements: FEATURE-BLOCK-LISTS.md
covers: BLOCK-003
context: sources/spec.txt, sources/spec_tests.py
context_roles: |
spec.txt: normative specification and conformance test suite
spec_tests.py: conformance harness
stack: common.md, python.md
provides: list parser
consumes: leaf block parser, block quote parser
depends: block-quotes
acceptance: yes
scope: target
instructions: |
Implement bullet and ordered lists, nesting, lazy continuation, empty items, marker indentation, delimiter changes, and tight versus loose rendering metadata.
## story inline-escapes
summary: Parse escapes and character references.
type: service
kind: capability
phase: 3
implements: FEATURE-INLINE-ESCAPES.md
covers: INLINE-001
context: sources/spec.txt, sources/spec_tests.py
context_roles: |
spec.txt: normative specification and conformance test suite
spec_tests.py: conformance harness
stack: common.md, python.md
provides: escape parser, character reference parser
consumes: block parser
depends: block-lists
acceptance: yes
scope: target
instructions: |
Implement punctuation escapes, named entities, decimal and hexadecimal references, invalid-code-point replacement, and context restrictions.
## story inline-code-breaks
summary: Parse code spans and line breaks.
type: service
kind: capability
phase: 3
implements: FEATURE-INLINE-CODE-BREAKS.md
covers: INLINE-002
context: sources/spec.txt, sources/spec_tests.py
context_roles: |
spec.txt: normative specification and conformance test suite
spec_tests.py: conformance harness
stack: common.md, python.md
provides: code span parser, hard break parser, soft break parser
consumes: block parser
depends: block-lists
acceptance: yes
scope: target
instructions: |
Implement delimiter-length code spans, code-span normalization, hard breaks, soft breaks, and trailing-space behavior.
## story inline-emphasis
summary: Parse emphasis and strong emphasis using delimiter rules.
type: service
kind: capability
phase: 3
implements: FEATURE-INLINE-EMPHASIS.md
covers: INLINE-003
context: sources/spec.txt, sources/spec_tests.py
context_roles: |
spec.txt: normative specification and conformance test suite
spec_tests.py: conformance harness
stack: common.md, python.md
provides: emphasis parser, strong emphasis parser
consumes: block parser, code span parser
depends: inline-code-breaks
acceptance: yes
scope: target
instructions: |
Implement delimiter runs, flanking rules, intraword restrictions, nesting, precedence, and the modulo-three constraints for emphasis and strong emphasis.
## story inline-links
summary: Parse links and images.
type: service
kind: capability
phase: 3
implements: FEATURE-INLINE-LINKS.md
covers: INLINE-004
context: sources/spec.txt, sources/spec_tests.py
context_roles: |
spec.txt: normative specification and conformance test suite
spec_tests.py: conformance harness
stack: common.md, python.md
provides: link parser, image parser, reference resolver
consumes: block parser, inline parser
depends: inline-emphasis
acceptance: yes
scope: target
instructions: |
Implement inline, full-reference, collapsed-reference, and shortcut links; nested image descriptions; balanced destinations; titles; and reference definition precedence.
## story inline-html
summary: Parse autolinks and raw HTML.
type: service
kind: capability
phase: 3
implements: FEATURE-INLINE-HTML.md
covers: INLINE-005
context: sources/spec.txt, sources/spec_tests.py
context_roles: |
spec.txt: normative specification and conformance test suite
spec_tests.py: conformance harness
stack: common.md, python.md
provides: autolink parser, raw HTML parser
consumes: block parser, inline parser
depends: inline-links
acceptance: yes
scope: target
instructions: |
Implement URI and email autolinks plus raw HTML tags, comments, declarations, processing instructions, and CDATA while preserving raw markup.
## story render-blocks
summary: Render parsed block structure as CommonMark HTML.
type: service
kind: capability
phase: 4
implements: FEATURE-RENDER-BLOCKS.md
covers: RENDER-001
context: sources/spec.txt, sources/spec_tests.py, sources/normalize.py
context_roles: |
spec.txt: normative specification and conformance test suite
spec_tests.py: conformance harness
normalize.py: parser-to-normalizer
stack: common.md, python.md
provides: block HTML renderer
consumes: block parser, inline parser
depends: inline-html
acceptance: yes
scope: target
instructions: |
Render headings, paragraphs, thematic breaks, code blocks, block quotes, lists, list tightness, and escaped block content with required CommonMark HTML structure.
## story render-inline
summary: Render parsed inline structure as CommonMark HTML.
type: service
kind: capability
phase: 4
implements: FEATURE-RENDER-INLINE.md
covers: RENDER-002
context: sources/spec.txt, sources/spec_tests.py, sources/normalize.py
context_roles: |
spec.txt: normative specification and conformance test suite
spec_tests.py: conformance harness
normalize.py: parser-to-normalizer
stack: common.md, python.md
provides: inline HTML renderer
consumes: inline parser
depends: render-blocks
acceptance: yes
scope: target
instructions: |
Render text, links, images, code, emphasis, strong emphasis, breaks, entities, and raw HTML with required escaping and preservation rules.
## story render-normalization
summary: Normalize URL, title, attribute, and special-character output.
type: service
kind: integration
phase: 4
implements: FEATURE-RENDER-NORMALIZATION.md
covers: RENDER-003
context: sources/spec.txt, sources/spec_tests.py, sources/normalize.py
context_roles: |
spec.txt: normative specification and conformance test suite
spec_tests.py: conformance harness
normalize.py: parser-to-normalizer
stack: common.md, python.md
provides: normalized URL output, normalized title output, normalized attribute output
consumes: block HTML renderer, inline HTML renderer
depends: render-inline
acceptance: yes
scope: target
instructions: |
Ensure URL escaping, title escaping, attribute ordering and escaping, entity handling, and special-character output match the supplied harness expectations.
## story conformance-assets
summary: Stage and exercise the supplied conformance harness within bounded story scopes.
type: service
kind: test harness
phase: 4
implements: FEATURE-CONFORMANCE-ASSETS.md
covers: VERIFY-001, VERIFY-002
context: sources/spec.txt, sources/spec_tests.py, sources/cmark.py, sources/normalize.py
context_roles: |
spec.txt: normative specification and conformance test suite
spec_tests.py: conformance harness
cmark.py: test helper
normalize.py: test helper
copy: |
sources/spec.txt -> spec.txt
sources/spec_tests.py -> spec_tests.py
sources/cmark.py -> cmark.py
sources/normalize.py -> normalize.py
stack: common.md, python.md
provides: staged conformance assets, bounded conformance verification
consumes: parser executable
depends: render-normalization
acceptance: yes
scope: both
instructions: |
Stage only spec.txt, spec_tests.py, cmark.py, and normalize.py at the runtime paths required by the harness. Add bounded selector-based verification for the implementation stories without invoking an unfiltered suite.
## story conformance-full
summary: Run the complete supplied CommonMark conformance suite.
type: service
kind: test harness
phase: 5
implements: FEATURE-CONFORMANCE-FULL.md
covers: VERIFY-003
accepts: st-001
context: sources/spec.txt, sources/spec_tests.py, sources/cmark.py, sources/normalize.py
context_roles: |
spec.txt: normative specification and conformance test suite
spec_tests.py: conformance harness
cmark.py: test helper
normalize.py: test helper
stack: common.md, python.md
provides: full_test.sh, complete conformance verification
consumes: parser executable, staged conformance assets
depends: cli-entrypoint, cli-errors, cli-documentation, block-leaf, block-quotes, block-lists, inline-escapes, inline-code-breaks, inline-emphasis, inline-links, inline-html, render-blocks, render-inline, render-normalization, conformance-assets
acceptance: yes
scope: target
instructions: |
Create full_test.sh as a POSIX-compatible wrapper for the complete unfiltered supplied suite. The terminal acceptance runs sh full_test.sh with Suite: full, prints captured output and error, and asserts only exit status zero. It carries Sea Trials: st-001.
=== END TOPOLOGY.md ===
=== DECISIONS.json ===
[
{
"id": "Q-001",
"type": "choice",
"severity": "material",
"blueprint": "ARCHITECTURE.md",
"story": "architecture",
"title": "Parser implementation structure",
"description": "The parser is implemented as a two-phase Python command-line application with independently testable block parsing, inline parsing, rendering, and process boundaries.",
"options": [
{
"value": "single-module",
"label": "Single parser module"
},
{
"value": "layered-modules",
"label": "Layered parser modules"
}
],
"system_choice": "layered-modules"
},
{
"id": "Q-002",
"type": "choice",
"severity": "low",
"blueprint": "FEATURE-CONFORMANCE-FULL.md",
"story": "conformance-full",
"title": "Full-suite wrapper",
"description": "The complete verification command is provided by a repository-local POSIX shell wrapper that invokes the staged Python harness without filtering.",
"options": [
{
"value": "shell-wrapper",
"label": "POSIX shell wrapper"
},
{
"value": "direct-python",
"label": "Direct Python invocation"
}
],
"system_choice": "shell-wrapper"
}
]
=== END DECISIONS.json ===Run artifact