---
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.