# 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