generated from coulomb/repo-seed
chore: workplan MRKD-WP-0001 + improved CLAUDE.md; document next steps
- workplans/MRKD-WP-0001-foundation-level1.md: 8-task workplan for Foundation & LEVEL1 Core (T01 scaffolding through T08 e2e harness) - CLAUDE.md: added Planned Architecture section (interface table, FR domain map, key concepts, round-trip data flow) and Development Commands stubs derived from FRS v0.2 - problems/next-steps-2026-03-14.md: implementation guide for next session — task order, dep list, state-hub task UUIDs, quality gates No code implemented yet; workstream registered in State Hub. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
191
workplans/MRKD-WP-0001-foundation-level1.md
Normal file
191
workplans/MRKD-WP-0001-foundation-level1.md
Normal file
@@ -0,0 +1,191 @@
|
||||
---
|
||||
id: MRKD-WP-0001
|
||||
type: workplan
|
||||
domain: markitect
|
||||
repo: marki-docx
|
||||
status: active
|
||||
state_hub_workstream_id: de855681-7ce0-4ace-b283-ec61f7557066
|
||||
created: 2026-03-14
|
||||
updated: 2026-03-14
|
||||
---
|
||||
|
||||
# MRKD-WP-0001 — Foundation & LEVEL1 Core
|
||||
|
||||
Build the markidocx Python package from scratch through a working LEVEL1 round-trip CLI.
|
||||
This workstream covers all functional prerequisites: package scaffolding, manifest model,
|
||||
MD→DOCX build, DOCX→MD import, three template family stubs, validation + drift detection,
|
||||
and an end-to-end regression harness using the specs as the test corpus.
|
||||
|
||||
**Scope:** FR-100, FR-200, FR-300, FR-400, FR-500 (LEVEL1), FR-600 (stubs), FR-700, FR-800, FR-1100
|
||||
**Out of scope:** REST service (FR-900), MCP tools (FR-1000), LEVEL3 features (FR-531–542)
|
||||
|
||||
---
|
||||
|
||||
## T01 — Project scaffolding
|
||||
|
||||
```task
|
||||
id: MRKD-WP-0001-T01
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: 5dd0e377-2a4e-4ddd-a6fa-aeb097ead292
|
||||
```
|
||||
|
||||
Set up the Python package: `pyproject.toml`, `src/markidocx/` layout, ruff + mypy config,
|
||||
pytest, pre-commit hooks, and CI skeleton. No functional code — just a working dev environment.
|
||||
|
||||
Deliverable: `pip install -e ".[dev]"` works, `pytest` collects 0 tests without error,
|
||||
`ruff check .` and `mypy src/` exit clean.
|
||||
|
||||
---
|
||||
|
||||
## T02 — Manifest model (FR-100)
|
||||
|
||||
```task
|
||||
id: MRKD-WP-0001-T02
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: d381a578-821a-44f0-b1a2-5254966aae48
|
||||
```
|
||||
|
||||
Define the project manifest schema (YAML): source files, feature level, template/style family,
|
||||
document metadata. Implement FR-101–110:
|
||||
|
||||
- Parse and validate a manifest file
|
||||
- Detect missing referenced resources (FR-103)
|
||||
- Expose project inspection and capability disclosure (FR-104, FR-105)
|
||||
- Warn on unsupported configuration (FR-106)
|
||||
- Report resolution status (FR-109)
|
||||
|
||||
Deliverable: `markidocx validate <manifest.yaml>` exits 0 on valid, 1 on error, 2 on warnings.
|
||||
|
||||
---
|
||||
|
||||
## T03 — LEVEL1 build / MD→DOCX export (FR-200, FR-501–508)
|
||||
|
||||
```task
|
||||
id: MRKD-WP-0001-T03
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: 2c466852-d136-48cf-ba53-8c999f11527e
|
||||
```
|
||||
|
||||
Implement Markdown composition and DOCX export at LEVEL1 feature coverage:
|
||||
|
||||
- Headings (FR-501), lists (FR-502), tables (FR-503), footnotes (FR-504),
|
||||
images (FR-506), links (FR-506)
|
||||
- Template application (FR-204), metadata propagation (FR-207)
|
||||
- Build result reporting: success/warning/failure, artifact path, family + feature-level
|
||||
disclosure (FR-208–211)
|
||||
- Surface unsupported constructs explicitly rather than silently accepting them (FR-508)
|
||||
|
||||
Deliverable: `markidocx build <manifest.yaml>` produces a valid DOCX for a LEVEL1 document.
|
||||
|
||||
---
|
||||
|
||||
## T04 — LEVEL1 import / DOCX→MD round-trip (FR-300, FR-400)
|
||||
|
||||
```task
|
||||
id: MRKD-WP-0001-T04
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: 117a5de0-eeef-4358-8c78-fed26ae55f2b
|
||||
```
|
||||
|
||||
Implement DOCX import with project-aware context:
|
||||
|
||||
- Markdown reconstitution at LEVEL1 (FR-303, FR-304)
|
||||
- Source redistribution for multi-file projects using source mapping (FR-305, FR-405)
|
||||
- Fallback merged output when redistribution cannot complete safely (FR-406)
|
||||
- Import result and mapping status reporting (FR-306, FR-311, FR-312)
|
||||
- Section boundary integrity reporting (FR-407)
|
||||
|
||||
Deliverable: `markidocx import <manifest.yaml> <edited.docx>` writes redistributed Markdown
|
||||
files (or fallback merge) and exits with structured status.
|
||||
|
||||
---
|
||||
|
||||
## T05 — Template & style family stubs: article, book, website (FR-600)
|
||||
|
||||
```task
|
||||
id: MRKD-WP-0001-T05
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: 3d10a43b-301d-4717-9ab4-f43851058c3f
|
||||
```
|
||||
|
||||
Create the three built-in DOCX template families (`article`, `book`, `website`) with
|
||||
matching style definitions. Families need not be fully designed — structurally correct
|
||||
for LEVEL1 is sufficient.
|
||||
|
||||
- Family metadata and discovery (FR-602, FR-603, FR-604)
|
||||
- Template registration and paired-family registration (FR-605, FR-606, FR-607)
|
||||
- Registration validation (FR-608)
|
||||
|
||||
Deliverable: `markidocx template list` returns all three families; each produces a
|
||||
valid DOCX when used in a build.
|
||||
|
||||
---
|
||||
|
||||
## T06 — Validation & drift detection (FR-700)
|
||||
|
||||
```task
|
||||
id: MRKD-WP-0001-T06
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: 0390f7d3-a9c3-4cac-a295-303adfe82960
|
||||
```
|
||||
|
||||
Implement structural diff between baseline Markdown and re-imported result:
|
||||
|
||||
- Compare heading hierarchy, list structure, table presence, footnotes, links
|
||||
- Classify each construct as preserved / degraded / broken / unsupported
|
||||
- Produce a drift report as an inspectable evidence artefact (JSON + human-readable)
|
||||
|
||||
Deliverable: `markidocx compare <manifest.yaml> <edited.docx>` exits 0 (no drift),
|
||||
1 (drift detected), or 2 (comparison failed), and writes a drift report.
|
||||
|
||||
---
|
||||
|
||||
## T07 — CLI interface (FR-800)
|
||||
|
||||
```task
|
||||
id: MRKD-WP-0001-T07
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: 2e455d87-9044-411e-91c7-3a512488904a
|
||||
```
|
||||
|
||||
Wire the functional core to a CLI entry point. Commands:
|
||||
|
||||
| Command | Maps to |
|
||||
|---------|---------|
|
||||
| `markidocx build <manifest>` | FR-200 build |
|
||||
| `markidocx import <manifest> <docx>` | FR-300 import |
|
||||
| `markidocx compare <manifest> <docx>` | FR-700 drift |
|
||||
| `markidocx validate <manifest>` | FR-100 resolution |
|
||||
| `markidocx template list` | FR-603 |
|
||||
| `markidocx template register <path>` | FR-605 |
|
||||
|
||||
Machine-readable output flag (`--json`). Exit codes: 0 success, 1 error, 2 warning (per FR-1200).
|
||||
|
||||
---
|
||||
|
||||
## T08 — End-to-end test harness & regression corpus (FR-1100)
|
||||
|
||||
```task
|
||||
id: MRKD-WP-0001-T08
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: ca3ecede-aef3-48b0-b21b-2b9f59167cb5
|
||||
```
|
||||
|
||||
Build the round-trip regression harness using the markidocx specs as the test corpus
|
||||
(per the FRS intent that product documentation serves as a stable validation corpus):
|
||||
|
||||
- `build → import → compare` cycle for each spec document at LEVEL1
|
||||
- Per-family smoke tests (article, book, website)
|
||||
- Drift-detection assertions: zero structural drift expected on a clean round-trip
|
||||
- CI-runnable with `pytest`
|
||||
|
||||
Deliverable: `pytest tests/regression/` passes on a clean round-trip; drift regressions
|
||||
cause test failures.
|
||||
Reference in New Issue
Block a user