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

Next Steps — 2026-03-14

Current state

• T01 DONE: pyproject.toml, src/markidocx/__init__.py, tests/ scaffold, package installed (markidocx.egg-info present)
• T07 DONE (skeleton): src/markidocx/cli.py — full CLI wired up with all commands (build, import, compare, validate, template list/register). Imports from modules that don't yet exist.
• T02–T06, T08 TODO: no implementation files yet

Files that must be created next

src/markidocx/manifest.py (T02)

# Manifest YAML schema:
# project:
#   name: str
#   feature_level: level1 | level3
#   family: article | book | website
# sources:
#   - path: relative/path.md
# output:
#   dir: ./dist
# metadata:
#   title: str
#   author: str
#   date: str

@dataclass
class ProjectConfig: name, feature_level, family
@dataclass
class SourceEntry: path (Path)
@dataclass
class Manifest: project, sources, output_dir, metadata
class ManifestError(Exception): pass
def load_manifest(path: Path) -> Manifest: ...

Tests: tests/test_manifest.py

src/markidocx/templates.py (T05)

@dataclass
class FamilyDefinition: name, description, template_path
class FamilyRegistry:
    def list_families() -> list[FamilyDefinition]
    def get_family(name) -> FamilyDefinition
    def register(path, name, description) -> None

Template .docx files in src/markidocx/templates/ (article.docx, book.docx, website.docx). Create them programmatically in a _create_templates.py script or in a pytest fixture. Tests: tests/test_templates.py

src/markidocx/builder.py (T03)

@dataclass
class BuildResult: success, output_path, family, feature_level, warnings, errors
def build_document(manifest: Manifest) -> BuildResult: ...

Uses mistune to parse Markdown, python-docx to write DOCX. Embed source boundary XML part (<markidocx:sources>) for multi-file redistribution. LEVEL1 elements: H1-H6, ordered/unordered lists, tables, footnotes, images, links, bold/italic. Tests: tests/test_builder.py

src/markidocx/importer.py (T04)

@dataclass
class ImportResult: success, output_files, warnings, mapping_status
def import_document(manifest: Manifest, docx_path: Path) -> ImportResult: ...

Uses python-docx to read DOCX, convert to Markdown. Read embedded source boundary XML → redistribute to original files. Fallback: single merged output when no boundaries found. Tests: tests/test_importer.py

src/markidocx/differ.py (T06)

@dataclass
class DriftReport: preserved, degraded, broken, unsupported, has_drift
def compare(original: str, reimported: str) -> DriftReport: ...

Structural comparison: heading counts/titles, list counts, table counts, footnote counts. Tests: tests/test_differ.py

tests/test_e2e.py (T08)

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

Architecture ADRs to write

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

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

• T01: 5dd0e377-2a4e-4ddd-a6fa-aeb097ead292 ← ALREADY DONE
• 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 ← skeleton done, mark done after T02-T06 import
• T08: ca3ecede-aef3-48b0-b21b-2b9f59167cb5

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

Quality gates before marking workstream done

• ruff check src/ tests/ — no errors
• mypy src/markidocx/ — no errors
• pytest tests/ -v — all pass
• markidocx --help works
• markidocx build <manifest> produces a .docx
• markidocx validate <manifest> exits 0 on valid manifest