marki-docx/problems/next-steps-2026-03-14.md

Next Steps — 2026-03-14

Status

Ralph loop iteration 1 was interrupted before implementation began. No code has been written yet — repo contains only specs, workplan, and CLAUDE.md.

What needs to happen (in order)

T01 — Project scaffolding

Create pyproject.toml (name: markidocx, Python >=3.11), src/markidocx/__init__.py, src/markidocx/cli.py (typer stub), tests/__init__.py, tests/conftest.py.

Key deps: python-docx, pyyaml, typer, rich, mistune Dev deps: pytest, pytest-cov, ruff, mypy, types-PyYAML

Install: pip install -e ".[dev]"

T02 — Manifest model (src/markidocx/manifest.py)

YAML schema: project (name, feature_level, family), sources (list of paths), output.dir, metadata. Implement: load_manifest(), Manifest dataclass, ManifestError, resolution status reporting. Tests: tests/test_manifest.py

T03 — LEVEL1 build (src/markidocx/builder.py)

Markdown → DOCX using python-docx + mistune. LEVEL1 elements: headings, lists, tables, footnotes, images, links, bold/italic. BuildResult dataclass. Embed source-boundary XML part for multi-file round-trips. Tests: tests/test_builder.py

T05 — Template families (src/markidocx/templates.py)

Three families: article, book, website — created programmatically with python-docx, stored as package data in src/markidocx/templates/. FamilyRegistry with list/get/register. Tests: tests/test_templates.py

T04 — LEVEL1 import (src/markidocx/importer.py)

DOCX → Markdown using python-docx. Redistribute to source files using embedded boundary XML. Fallback: single merged output. ImportResult dataclass. Tests: tests/test_importer.py

T06 — Drift detection (src/markidocx/differ.py)

Structural diff between original and re-imported Markdown. DriftReport dataclass (preserved/degraded/broken/unsupported). Tests: tests/test_differ.py

T07 — CLI (src/markidocx/cli.py)

Typer commands: build, import, compare, validate, template list/register. --json flag, exit codes 0/1/2.

T08 — E2E harness (tests/test_e2e.py)

Round-trip the spec files through build→import→compare. Smoke test each family. Assert zero drift on headings/lists.

Architecture decisions to write

• architecture/ADR-002-python-docx-as-conversion-engine.md
• architecture/ADR-003-manifest-yaml-schema.md

State Hub task IDs (mark done as each task completes)

• T01: 5dd0e377-2a4e-4ddd-a6fa-aeb097ead292
• T02: d381a578-821a-44f0-b1a2-5254966aae48
• T03: 2c466852-d136-48cf-ba53-8c999f11527e
• T04: 117a5de0-eeef-4358-8c78-fed26ae55f2b
• T05: 3d10a43b-301d-4717-9ab4-f43851058c3f
• T06: 0390f7d3-a9c3-4cac-a295-303adfe82960
• T07: 2e455d87-9044-411e-91c7-3a512488904a
• T08: ca3ecede-aef3-48b0-b21b-2b9f59167cb5

Workstream ID: de855681-7ce0-4ace-b283-ec61f7557066 Topic ID: 5571d954-0d30-4950-980d-7bcaaad8e3e2

Quality gates before marking done

• ruff check src/ tests/ — no errors
• mypy src/markidocx/ — no errors
• pytest tests/ -v — all pass
• markidocx --help works
• markidocx build + markidocx validate work on a simple manifest