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

---
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 <manifest.yaml>` 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 <manifest.yaml>` 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 <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)

```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 <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)

```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 <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)

```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.