From 0063fd8fcc6f54f5f5f991e2eaca691a9c08b2c4 Mon Sep 17 00:00:00 2001 From: tegwick Date: Fri, 15 May 2026 13:30:47 +0200 Subject: [PATCH] Add Quarkdown render adapter workplan --- ...-0001-quarkdown-render-adapter-boundary.md | 172 ++++++++++++++++++ 1 file changed, 172 insertions(+) create mode 100644 workplans/MQD-WP-0001-quarkdown-render-adapter-boundary.md diff --git a/workplans/MQD-WP-0001-quarkdown-render-adapter-boundary.md b/workplans/MQD-WP-0001-quarkdown-render-adapter-boundary.md new file mode 100644 index 0000000..070edb9 --- /dev/null +++ b/workplans/MQD-WP-0001-quarkdown-render-adapter-boundary.md @@ -0,0 +1,172 @@ +--- +id: MQD-WP-0001 +type: workplan +title: "Quarkdown Render Adapter Boundary" +domain: markitect +status: todo +owner: markitect-quarkdown +topic_slug: markitect +planning_priority: P2 +planning_order: 10 +related_workplans: + - MKTT-WP-0020 + - MKTT-WP-0021 + - MKTT-WP-0015 + - MKTF-WP-0003 +created: "2026-05-15" +updated: "2026-05-15" +state_hub_workstream_id: "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 + +## P1.1 - Map Markitect render contract to Quarkdown invocation + +```task +id: MQD-WP-0001-T001 +status: todo +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 + +```task +id: MQD-WP-0001-T002 +status: todo +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 + +```task +id: MQD-WP-0001-T003 +status: todo +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 + +```task +id: MQD-WP-0001-T004 +status: todo +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 + +```task +id: MQD-WP-0001-T005 +status: todo +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 + +```task +id: MQD-WP-0001-T006 +status: todo +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.