marki-docx/workplans/MRKD-WP-0001-foundation-level1.md

id, type, domain, repo, status, state_hub_workstream_id, created, updated

id	type	domain	repo	status	state_hub_workstream_id	created	updated
MRKD-WP-0001	workplan	markitect	marki-docx	done	de855681-7ce0-4ace-b283-ec61f7557066	2026-03-14	2026-03-16

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

id: MRKD-WP-0001-T01
status: done
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)

id: MRKD-WP-0001-T02
status: done
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 <manifest.yaml> exits 0 on valid, 1 on error, 2 on warnings.

---

T03 — LEVEL1 build / MD→DOCX export (FR-200, FR-501–508)

id: MRKD-WP-0001-T03
status: done
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 <manifest.yaml> produces a valid DOCX for a LEVEL1 document.

---

T04 — LEVEL1 import / DOCX→MD round-trip (FR-300, FR-400)

id: MRKD-WP-0001-T04
status: done
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 <manifest.yaml> <edited.docx> writes redistributed Markdown files (or fallback merge) and exits with structured status.

---

T05 — Template & style family stubs: article, book, website (FR-600)

id: MRKD-WP-0001-T05
status: done
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)

id: MRKD-WP-0001-T06
status: done
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 <manifest.yaml> <edited.docx> exits 0 (no drift), 1 (drift detected), or 2 (comparison failed), and writes a drift report.

---

T07 — CLI interface (FR-800)

id: MRKD-WP-0001-T07
status: done
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 <manifest>	FR-200 build
markidocx import <manifest> <docx>	FR-300 import
markidocx compare <manifest> <docx>	FR-700 drift
markidocx validate <manifest>	FR-100 resolution
markidocx template list	FR-603
markidocx template register <path>	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)

id: MRKD-WP-0001-T08
status: done
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.