generated from coulomb/repo-seed
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 <noreply@anthropic.com>
This commit is contained in:
@@ -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 (`<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`
|
||||
|
||||
### 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 <manifest>` produces a .docx
|
||||
- `markidocx validate <manifest>` exits 0 on valid manifest
|
||||
|
||||
Reference in New Issue
Block a user