--- id: MRKD-WP-0001 type: workplan domain: markitect repo: marki-docx status: active state_hub_workstream_id: de855681-7ce0-4ace-b283-ec61f7557066 created: 2026-03-14 updated: 2026-03-14 --- # MRKD-WP-0001 — Foundation & LEVEL1 Core Build the markidocx Python package from scratch through a working LEVEL1 round-trip CLI. This workstream covers all functional prerequisites: package scaffolding, manifest model, MD→DOCX build, DOCX→MD import, three template family stubs, validation + drift detection, and an end-to-end regression harness using the specs as the test corpus. **Scope:** FR-100, FR-200, FR-300, FR-400, FR-500 (LEVEL1), FR-600 (stubs), FR-700, FR-800, FR-1100 **Out of scope:** REST service (FR-900), MCP tools (FR-1000), LEVEL3 features (FR-531–542) --- ## T01 — Project scaffolding ```task id: MRKD-WP-0001-T01 status: todo priority: high state_hub_task_id: 5dd0e377-2a4e-4ddd-a6fa-aeb097ead292 ``` Set up the Python package: `pyproject.toml`, `src/markidocx/` layout, ruff + mypy config, pytest, pre-commit hooks, and CI skeleton. No functional code — just a working dev environment. Deliverable: `pip install -e ".[dev]"` works, `pytest` collects 0 tests without error, `ruff check .` and `mypy src/` exit clean. --- ## T02 — Manifest model (FR-100) ```task id: MRKD-WP-0001-T02 status: todo priority: high state_hub_task_id: d381a578-821a-44f0-b1a2-5254966aae48 ``` Define the project manifest schema (YAML): source files, feature level, template/style family, document metadata. Implement FR-101–110: - Parse and validate a manifest file - Detect missing referenced resources (FR-103) - Expose project inspection and capability disclosure (FR-104, FR-105) - Warn on unsupported configuration (FR-106) - Report resolution status (FR-109) Deliverable: `markidocx validate ` exits 0 on valid, 1 on error, 2 on warnings. --- ## T03 — LEVEL1 build / MD→DOCX export (FR-200, FR-501–508) ```task id: MRKD-WP-0001-T03 status: todo priority: high state_hub_task_id: 2c466852-d136-48cf-ba53-8c999f11527e ``` Implement Markdown composition and DOCX export at LEVEL1 feature coverage: - Headings (FR-501), lists (FR-502), tables (FR-503), footnotes (FR-504), images (FR-506), links (FR-506) - Template application (FR-204), metadata propagation (FR-207) - Build result reporting: success/warning/failure, artifact path, family + feature-level disclosure (FR-208–211) - Surface unsupported constructs explicitly rather than silently accepting them (FR-508) Deliverable: `markidocx build ` produces a valid DOCX for a LEVEL1 document. --- ## T04 — LEVEL1 import / DOCX→MD round-trip (FR-300, FR-400) ```task id: MRKD-WP-0001-T04 status: todo priority: high state_hub_task_id: 117a5de0-eeef-4358-8c78-fed26ae55f2b ``` Implement DOCX import with project-aware context: - Markdown reconstitution at LEVEL1 (FR-303, FR-304) - Source redistribution for multi-file projects using source mapping (FR-305, FR-405) - Fallback merged output when redistribution cannot complete safely (FR-406) - Import result and mapping status reporting (FR-306, FR-311, FR-312) - Section boundary integrity reporting (FR-407) Deliverable: `markidocx import ` writes redistributed Markdown files (or fallback merge) and exits with structured status. --- ## T05 — Template & style family stubs: article, book, website (FR-600) ```task id: MRKD-WP-0001-T05 status: todo priority: medium state_hub_task_id: 3d10a43b-301d-4717-9ab4-f43851058c3f ``` Create the three built-in DOCX template families (`article`, `book`, `website`) with matching style definitions. Families need not be fully designed — structurally correct for LEVEL1 is sufficient. - Family metadata and discovery (FR-602, FR-603, FR-604) - Template registration and paired-family registration (FR-605, FR-606, FR-607) - Registration validation (FR-608) Deliverable: `markidocx template list` returns all three families; each produces a valid DOCX when used in a build. --- ## T06 — Validation & drift detection (FR-700) ```task id: MRKD-WP-0001-T06 status: todo priority: medium state_hub_task_id: 0390f7d3-a9c3-4cac-a295-303adfe82960 ``` Implement structural diff between baseline Markdown and re-imported result: - Compare heading hierarchy, list structure, table presence, footnotes, links - Classify each construct as preserved / degraded / broken / unsupported - Produce a drift report as an inspectable evidence artefact (JSON + human-readable) Deliverable: `markidocx compare ` exits 0 (no drift), 1 (drift detected), or 2 (comparison failed), and writes a drift report. --- ## T07 — CLI interface (FR-800) ```task id: MRKD-WP-0001-T07 status: todo priority: medium state_hub_task_id: 2e455d87-9044-411e-91c7-3a512488904a ``` Wire the functional core to a CLI entry point. Commands: | Command | Maps to | |---------|---------| | `markidocx build ` | FR-200 build | | `markidocx import ` | FR-300 import | | `markidocx compare ` | FR-700 drift | | `markidocx validate ` | FR-100 resolution | | `markidocx template list` | FR-603 | | `markidocx template register ` | FR-605 | Machine-readable output flag (`--json`). Exit codes: 0 success, 1 error, 2 warning (per FR-1200). --- ## T08 — End-to-end test harness & regression corpus (FR-1100) ```task id: MRKD-WP-0001-T08 status: todo priority: medium state_hub_task_id: ca3ecede-aef3-48b0-b21b-2b9f59167cb5 ``` Build the round-trip regression harness using the markidocx specs as the test corpus (per the FRS intent that product documentation serves as a stable validation corpus): - `build → import → compare` cycle for each spec document at LEVEL1 - Per-family smoke tests (article, book, website) - Drift-detection assertions: zero structural drift expected on a clean round-trip - CI-runnable with `pytest` Deliverable: `pytest tests/regression/` passes on a clean round-trip; drift regressions cause test failures.