From e6232395950fc0d44aff41b21bcfd720acd1d486 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sat, 14 Mar 2026 18:22:42 +0100 Subject: [PATCH] chore: update next-steps doc with accurate current state 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 --- problems/next-steps-2026-03-14.md | 122 +++++++++++++++++++----------- 1 file changed, 77 insertions(+), 45 deletions(-) diff --git a/problems/next-steps-2026-03-14.md b/problems/next-steps-2026-03-14.md index ba5b3c4..fbb5465 100644 --- a/problems/next-steps-2026-03-14.md +++ b/problems/next-steps-2026-03-14.md @@ -1,76 +1,108 @@ # 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. +## 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 -## What needs to happen (in order) +## Files that must be created next -### 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`. +### `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 -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. +@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` -### 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. +### `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` -### 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. +### `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 (``) 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` -### T06 — Drift detection (`src/markidocx/differ.py`) -Structural diff between original and re-imported Markdown. -DriftReport dataclass (preserved/degraded/broken/unsupported). +### `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` -### T07 — CLI (`src/markidocx/cli.py`) -Typer commands: build, import, compare, validate, template list/register. ---json flag, exit codes 0/1/2. +### `tests/test_e2e.py` (T08) +Round-trip the PRD spec through build→import→compare. +Smoke test each family. Assert zero structural drift on headings. -### 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 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 as each task completes) -- T01: 5dd0e377-2a4e-4ddd-a6fa-aeb097ead292 +## 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 +- 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 done +## 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` + `markidocx validate` work on a simple manifest +- `markidocx build ` produces a .docx +- `markidocx validate ` exits 0 on valid manifest