marki-docx/workplans/MRKD-WP-0002-service-interfaces.md

id, type, domain, repo, status, state_hub_workstream_id, created, updated

id	type	domain	repo	status	state_hub_workstream_id	created	updated
MRKD-WP-0002	workplan	communication	marki-docx	done	6a7b5627-7593-4713-8e56-94c4ab3ff838	2026-03-16	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)

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)

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)

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)

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)

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

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.