coulomb/marki-docx
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: WP-0001 + WP-0002 complete — LEVEL1 core + service interfaces

Browse Source 
WP-0001 (Foundation & LEVEL1 Core):
- manifest model (FR-100), MD→DOCX builder (FR-200), DOCX→MD importer
  (FR-300/400), template family registry (FR-600), drift detector (FR-700),
  CLI wiring, pre-commit config, CI skeleton, regression harness

WP-0002 (Service Interfaces & Workflow Orchestration):
- REST service via FastAPI (FR-900): /health, /version, /capabilities,
  /templates, /styles, /validate, /build, /import, /compare,
  /templates/register, /workflows/{name}, /evidence/{run_id}
- Evidence & report store (FR-1400): JSON-backed, per-run, retrievable
  through all interfaces, classification (pass/warnings/failed)
- Composite workflow orchestration (FR-1300): single-file-roundtrip,
  multi-file-roundtrip, release-regression, family-switch-build
- MCP server via FastMCP (FR-1000): all tools + resources
- CLI additions: `markidocx serve`, `markidocx workflow`, `markidocx mcp`
- Interface parity tests: CLI / REST / MCP produce equivalent results

135 tests passing, ruff + mypy clean.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Bernd Worsch
2026-03-16 07:46:31 +00:00
parent 42789cad1e
commit 1f3dddf7d6
30 changed files with 4158 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
workplans/MRKD-WP-0001-foundation-level1.md
View File

@@ -3,10 +3,10 @@ id: MRKD-WP-0001
type: workplan
domain: markitect
repo: marki-docx
status: active
status: done
state_hub_workstream_id: de855681-7ce0-4ace-b283-ec61f7557066
created: 2026-03-14
updated: 2026-03-14
updated: 2026-03-16
---
# MRKD-WP-0001 — Foundation & LEVEL1 Core
@@ -25,7 +25,7 @@ and an end-to-end regression harness using the specs as the test corpus.
```task
id: MRKD-WP-0001-T01
status: todo
status: done
priority: high
state_hub_task_id: 5dd0e377-2a4e-4ddd-a6fa-aeb097ead292
```
@@ -42,7 +42,7 @@ Deliverable: `pip install -e ".[dev]"` works, `pytest` collects 0 tests without
```task
id: MRKD-WP-0001-T02
status: todo
status: done
priority: high
state_hub_task_id: d381a578-821a-44f0-b1a2-5254966aae48
```
@@ -64,7 +64,7 @@ Deliverable: `markidocx validate <manifest.yaml>` exits 0 on valid, 1 on error,
```task
id: MRKD-WP-0001-T03
status: todo
status: done
priority: high
state_hub_task_id: 2c466852-d136-48cf-ba53-8c999f11527e
```
@@ -86,7 +86,7 @@ Deliverable: `markidocx build <manifest.yaml>` produces a valid DOCX for a LEVEL
```task
id: MRKD-WP-0001-T04
status: todo
status: done
priority: high
state_hub_task_id: 117a5de0-eeef-4358-8c78-fed26ae55f2b
```
@@ -108,7 +108,7 @@ files (or fallback merge) and exits with structured status.
```task
id: MRKD-WP-0001-T05
status: todo
status: done
priority: medium
state_hub_task_id: 3d10a43b-301d-4717-9ab4-f43851058c3f
```
@@ -130,7 +130,7 @@ valid DOCX when used in a build.
```task
id: MRKD-WP-0001-T06
status: todo
status: done
priority: medium
state_hub_task_id: 0390f7d3-a9c3-4cac-a295-303adfe82960
```
@@ -150,7 +150,7 @@ Deliverable: `markidocx compare <manifest.yaml> <edited.docx>` exits 0 (no drift
```task
id: MRKD-WP-0001-T07
status: todo
status: done
priority: medium
state_hub_task_id: 2e455d87-9044-411e-91c7-3a512488904a
```
@@ -174,7 +174,7 @@ Machine-readable output flag (`--json`). Exit codes: 0 success, 1 error, 2 warni
```task
id: MRKD-WP-0001-T08
status: todo
status: done
priority: medium
state_hub_task_id: ca3ecede-aef3-48b0-b21b-2b9f59167cb5
```

171
workplans/MRKD-WP-0002-service-interfaces.md Normal file
View File

@@ -0,0 +1,171 @@
---
id: MRKD-WP-0002
type: workplan
domain: markitect
repo: marki-docx
status: done
state_hub_workstream_id: 6a7b5627-7593-4713-8e56-94c4ab3ff838
created: 2026-03-16
updated: 2026-03-17
---
# MRKD-WP-0002 — Service Interfaces & Workflow Orchestration
Expose the LEVEL1 functional core through REST and MCP interfaces, add composite
workflow orchestration, and introduce a persistent evidence & report layer.
This workstream turns the working LEVEL1 round-trip pipeline into a complete,
multi-interface service ready for pipeline integration and agentic use.
**Scope:** FR-900, FR-1000, FR-1300, FR-1400
**Out of scope:** LEVEL3 advanced features (FR-531–542) — deferred to WP-0003
**Depends on:** MRKD-WP-0001 (LEVEL1 core + CLI) — must be complete
---
## T01 — REST service foundation (FR-900 core)
```task
id: MRKD-WP-0002-T01
status: done
priority: high
state_hub_task_id: 9d514098-90bc-4efe-b68f-55c8e046cf7d
```
Stand up the FastAPI application that hosts the markidocx REST service. Covers
infrastructure, not yet the functional endpoints.
- `markidocx serve` entry point — start server with `--host`, `--port`, `--dev` flags (FR-901)
- Health response: `GET /health` → `{"status": "ok", "version": "..."}` (FR-910)
- Version response: `GET /version` (FR-911)
- Capability inspection: `GET /capabilities` — supported feature levels, families (FR-909)
- Structured response envelope: `{status, outputs, warnings, errors, context}` used by all endpoints (FR-912)
- `GET /templates` and `GET /styles` stub endpoints (FR-906, FR-907)
Deliverable: `markidocx serve` starts; health, version, capability endpoints respond; `pytest tests/test_rest_foundation.py` passes.
---
## T02 — REST functional endpoints (FR-902–908, FR-913–916)
```task
id: MRKD-WP-0002-T02
status: done
priority: high
state_hub_task_id: a7448414-2958-42f2-ae67-acd31964cd52
```
Implement the REST endpoints that mirror the CLI functional surface.
- `POST /validate` — submit manifest YAML, receive validation result (FR-902)
- `POST /build` — submit manifest + sources, receive DOCX artifact + build report (FR-903)
- `POST /import` — submit manifest + DOCX bytes, receive Markdown outputs + import report (FR-904)
- `POST /compare` — submit manifest + DOCX, receive drift report (FR-905)
- `POST /templates/register` — submit template registration, receive validation result (FR-908)
- `POST /workflows/{name}` — invoke a composite workflow by name (FR-913)
- `GET /evidence/{run_id}` — retrieve evidence artifacts for a completed run (FR-914)
- All responses include project/family/feature-level/workflow context where applicable (FR-915)
- Fallback and partial-result conditions surfaced explicitly in response envelope (FR-916)
Deliverable: All functional endpoints respond with correct structured output; `pytest tests/test_rest_endpoints.py` passes.
---
## T03 — Evidence & report storage (FR-1400)
```task
id: MRKD-WP-0002-T03
status: done
priority: high
state_hub_task_id: 5c5d7e7f-9158-435d-bfbb-64812035f448
```
Introduce a persistent evidence layer so reports from any operation can be stored,
retrieved, and assembled into a release evidence set. This is a prerequisite for T02
(REST evidence access) and T04 (workflow output aggregation).
- Report store: save validation, build, import, and drift reports keyed by `run_id` (FR-1401–1404)
- Warnings, ambiguities, fallback conditions stored as structured report content (FR-1405)
- Release evidence set assembly from multiple run outputs (FR-1406)
- Evidence composition disclosure: which reports/artifacts are in the set (FR-1407)
- Evidence status summary: success / warnings / fallbacks / failures across the set (FR-1408)
- Reports retrievable through all supported interfaces — report store is interface-agnostic (FR-1409)
- Traceability fields: project, family, feature level, workflow, run context (FR-1410)
- Human-readable (Markdown / plain text) and machine-readable (JSON) output formats (FR-1411, FR-1412)
- Incomplete report/evidence sets disclosed explicitly (FR-1413)
- Release decision support: clear pass / pass-with-warnings / failed classification (FR-1414)
Deliverable: Evidence store implemented; reports written by CLI operations are persisted and retrievable; `pytest tests/test_evidence.py` passes.
---
## T04 — Composite workflow orchestration (FR-1300)
```task
id: MRKD-WP-0002-T04
status: done
priority: medium
state_hub_task_id: 64f818e4-143b-4ab6-b083-7c757e0ddf11
```
Implement the orchestration layer that composes existing operations into named, reusable
workflows. Workflows must be exposed consistently across CLI, REST, and MCP (FR-1308).
- `single-file-roundtrip`: validate → build → import → compare for a single-file project (FR-1301)
- `multi-file-roundtrip`: inspect → validate → build → import → redistribute (or fallback) → compare (FR-1302)
- `release-regression`: end-to-end regression on the stable documentation corpus (FR-1306)
- `family-switch-build`: build the same project under all compatible families and report separately (FR-1307)
- Structured workflow result: per-step status + outputs aggregated into a single result (FR-1303)
- Step visibility: which steps were executed, which were skipped or failed (FR-1304)
- Workflow completion classification: full / with-fallback / partial / failed (FR-1305)
- Workflow identity: `run_id`, workflow name, timestamp — sufficient to associate outputs (FR-1309)
- Aggregate build + import + validation + comparison outputs into coherent workflow result (FR-1310)
- CLI: `markidocx workflow <name> <manifest>` — invokes named workflow
Deliverable: All four workflows executable via CLI and returning structured results with evidence stored; `pytest tests/test_workflows.py` passes.
---
## T05 — MCP server (FR-1000)
```task
id: MRKD-WP-0002-T05
status: done
priority: medium
state_hub_task_id: 71b76ede-e430-4e8a-ae88-fbaef8d8ad7f
```
Implement the MCP-compatible server that exposes the same functional surface as CLI/REST
to agentic clients.
- MCP server entry point: `markidocx mcp` — starts an MCP-compatible server (FR-1001)
- Tools: `list_templates` (FR-1002), `list_styles` (FR-1003), `validate_project` (FR-1004),
`inspect_project` (FR-1005), `build` (FR-1006), `import_docx` (FR-1007),
`compare` (FR-1008), `run_tests` (FR-1009), `get_version` (FR-1010)
- Tools: `invoke_workflow` (FR-1012), `get_evidence` (FR-1013)
- Resources: manifests, capabilities, template metadata, style metadata, corpus metadata (FR-1011)
- Capability context in each tool: project/family/feature-level compatibility pre-invocation (FR-1014)
- Fallback, ambiguity, degradation, and partial-result conditions surfaced in tool outputs (FR-1015)
Deliverable: MCP server starts; all tools callable; `pytest tests/test_mcp.py` passes.
---
## T06 — Interface integration tests
```task
id: MRKD-WP-0002-T06
status: done
priority: medium
state_hub_task_id: e6dc2d8e-3b75-4547-bc89-c409eaab6a18
```
End-to-end integration tests that exercise all three interfaces (CLI, REST, MCP) over the
same operations and assert equivalent results.
- Same single-file round-trip invoked via CLI, REST, and MCP — results must match (FR-1308)
- Workflow `single-file-roundtrip` exercised via all three interfaces
- Evidence artifacts written by REST and MCP operations retrievable and structurally correct
- `pytest tests/test_interface_parity.py` — asserts CLI / REST / MCP result equivalence
Deliverable: Interface parity test suite passes; evidence round-trip confirmed across all three interfaces.