# 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)
```python
# 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)
```python
@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)
```python
@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)
```python
@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)
```python
@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