generated from coulomb/repo-seed
Bernd Worsch
1f3dddf7d6
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>
172 lines
7.4 KiB
Markdown
172 lines
7.4 KiB
Markdown
---
|
||
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.
|