markitect-quarkdown/workplans/MQD-WP-0001-quarkdown-render-adapter-boundary.md

id, type, title, domain, status, owner, topic_slug, planning_priority, planning_order, related_workplans, created, updated, state_hub_workstream_id

id	type	title	domain	status	owner	topic_slug	planning_priority	planning_order	related_workplans	created	updated	state_hub_workstream_id
MQD-WP-0001	workplan	Quarkdown Render Adapter Boundary	markitect	done	markitect-quarkdown	markitect	complete	10	MKTT-WP-0020 MKTT-WP-0021 MKTT-WP-0015 MKTF-WP-0003	2026-05-15	2026-05-15	fb4ebcf9-21ba-455d-8982-63908663c130

MQD-WP-0001: Quarkdown Render Adapter Boundary

Purpose

Implement the concrete Quarkdown render integration in the native markitect-quarkdown repo, using the render/export adapter contract defined by markitect-tool rather than embedding Quarkdown execution in core Markitect.

This repository is the right home for Quarkdown-specific runtime assumptions, permission handling, CLI invocation, artifact validation, and open-reuse integration maintenance.

Boundary

markitect-quarkdown owns:

• Quarkdown CLI/distribution integration
• runtime dependency assumptions such as Java, Node.js, npm, and Puppeteer
• Quarkdown permission model mapping
• output directory and artifact validation rules
• PDF/HTML/profile-specific behavior
• upstream Quarkdown compatibility monitoring
• open-reuse Integration Definition metadata

markitect-quarkdown does not own:

• core Markitect document-function parsing
• source-format read adapters
• durable artifact storage or publication lifecycle
• enterprise authorization services
• a long-lived divergent Quarkdown fork

Implementation Summary

Completed as the initial native Quarkdown render adapter boundary:

• Added a Python package with a render.quarkdown descriptor registered under markitect_tool.render_export_adapters.
• Implemented MarkitectQuarkdownAdapter for inspect-profile, export-source, and controlled render-artifact execution.
• Added Markitect profile to Quarkdown document/output mapping, option schema, permission mapping, default output conventions, dry-run plan artifacts, and structured runtime/execution/artifact diagnostics.
• Added artifact validation with extension, non-empty, digest, media type, and source-to-artifact provenance.
• Added docs, an example render request, open-reuse integration metadata, and tests that use fake execution plus a real-runtime skip hook.

P1.1 - Map Markitect render contract to Quarkdown invocation

id: MQD-WP-0001-T001
status: done
priority: high
state_hub_task_id: "cb8014d5-9384-4736-8be4-a1f336a416c8"

Map the future MKTT-WP-0020 render/export request and result envelopes onto a MarkitectQuarkdownAdapter boundary.

The mapping should define:

• accepted Markitect-compatible source inputs
• Quarkdown source export expectations
• output profiles and artifact media types
• structured failure results
• provenance and source map fields returned to Markitect

Output: adapter boundary note and compatibility tests with contract fixtures.

P1.2 - Define Quarkdown profile and option mapping

id: MQD-WP-0001-T002
status: done
priority: high
state_hub_task_id: "57a11359-4888-48e9-978b-bf30ba86c961"

Define how Markitect render profiles map to Quarkdown document and output modes:

• plain
• docs
• slides
• paged
• static site or HTML
• PDF

Output: profile matrix, option schema, and examples.

P1.3 - Implement controlled CLI execution boundary

id: MQD-WP-0001-T003
status: done
priority: high
state_hub_task_id: "e0aa1eb2-39e2-40c6-bd03-c44910303ce9"

Implement Quarkdown invocation through a controlled adapter boundary with explicit capability metadata for filesystem writes, external process execution, and optional network/runtime dependencies.

Output: adapter implementation, structured diagnostics, and tests that can skip cleanly when Quarkdown runtime dependencies are unavailable.

P1.4 - Handle Quarkdown permissions and output conventions

id: MQD-WP-0001-T004
status: done
priority: high
state_hub_task_id: "c0d73105-ae4f-407e-9137-fe4216abd9c8"

Pin Quarkdown 2.x permission model behavior, default output directories, artifact naming, and PDF export assumptions.

Output: permission mapping docs, output convention tests, and compatibility notes.

P1.5 - Validate generated artifacts and provenance

id: MQD-WP-0001-T005
status: done
priority: medium
state_hub_task_id: "4719b31f-eec9-4e1b-a2e5-82a261ed8139"

Validate generated artifacts without making markitect-tool responsible for renderer behavior.

Validation should cover:

• expected artifact existence
• media type and file extension
• digest/checksum
• source-to-artifact provenance
• error interpretation for failed renders

Output: artifact validation helpers, fixtures, and tests.

P1.6 - Maintain open-reuse integration metadata

id: MQD-WP-0001-T006
status: done
priority: medium
state_hub_task_id: "f8c2c874-8fee-45b3-86fd-2fe7fc563ee8"

Represent the Quarkdown integration as an open-reuse Integration Definition so upstream change, dependency, license, and security risks can be monitored.

Output: integration definition, upstream version policy, risk profile, and maintenance checklist.

Exit Criteria

• Quarkdown render behavior lives in markitect-quarkdown, not markitect-tool or markitect-filter.
• The adapter can satisfy the MKTT-WP-0020 render/export contract once that contract exists.
• Runtime dependencies are optional, declared, and test-skippable.
• Generated artifacts have structured diagnostics, checksums, and provenance.
• Upstream Quarkdown compatibility is tracked as an open-reuse integration.