generated from coulomb/repo-seed
tegwick
e623239595
T01 (scaffolding) and T07 (CLI skeleton) are already present. Document exact files needed for T02-T06, T08 so next session can start implementing immediately. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
109 lines
3.9 KiB
Markdown
109 lines
3.9 KiB
Markdown
# 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
|