---
id: MRKD-WP-0003
type: workplan
domain: markitect
repo: marki-docx
status: done
state_hub_workstream_id: b04fe706-6e4e-48a8-b6c1-194d9e308215
created: 2026-03-17
updated: 2026-03-17
---

# MRKD-WP-0003 — LEVEL3 Advanced Features & Error Hardening

Implement LEVEL3 advanced document features and harden the error & warning
reporting framework across all modules. This workstream brings markidocx from
a LEVEL1-only system to full LEVEL3 capability: cross-references, numbered
figures, auto-diagrams, and bibliography/citations.

**Scope:** FR-531–542 (LEVEL3 features), FR-1201–1210 (error & warning behaviour)
**Out of scope:** REST/MCP interface changes — LEVEL3 features are exposed automatically
through the existing interface layer once the core modules support them.

**Depends on:** MRKD-WP-0002 (service interfaces + evidence layer) — must be complete

---

## T01 — LEVEL3 plumbing — feature-level gating & disclosure (FR-537–539)

```task
id: MRKD-WP-0003-T01
status: done
priority: high
state_hub_task_id: 51e1b53e-a62f-496b-892d-615513c35d67
```

Prerequisite for all LEVEL3 work. Ensures the system knows when it is
operating in LEVEL3 mode and can gate, disclose, and report accordingly.

- Manifest validation: `feature_level: level3` accepted and routes to LEVEL3 processing paths
- Capability disclosure: `/capabilities`, `validate_project`, and `get_version` surfaces `level3`
  as an available (but dependency-conditional) level (FR-537)
- Processor-dependency disclosure: when a LEVEL3 construct requires an external tool
  (e.g. diagram renderer), the system emits a structured dependency notice (FR-538)
- Partial-support reporting: when a LEVEL3 build/import completes with some advanced
  features unavailable, the result carries a `partial_level3` flag and lists missing coverage (FR-539)
- Unit tests for all gating and disclosure paths

Deliverable: `pytest tests/test_level3_plumbing.py` passes; level3 appears in capabilities.

---

## T02 — Error & warning framework hardening (FR-1201–1210)

```task
id: MRKD-WP-0003-T02
status: done
priority: high
state_hub_task_id: f4010618-9d35-4c04-bc1c-c599f254edff
```

Audit every module (builder, importer, differ, workflows, evidence, REST, MCP)
against FR-1201–1210. For each gap, add structured failure/warning objects
with severity and reason. No silent discards anywhere in the pipeline.

- `WarningRecord` / `FailureRecord` dataclasses: `severity` (info/warning/error),
  `reason` (FR-code-aligned string), `construct` (what triggered it) (FR-1208, FR-1209)
- `OutputState` enum: `final | partial | fallback | degraded | unresolved` — attached to
  all result objects (FR-1210)
- Builder: unsupported token types emit `WarningRecord`, not a bare string (FR-1203, FR-1205)
- Importer: ambiguous elements emit `WarningRecord` with reason (FR-1206)
- Differ: partial preservation tagged as degraded, not silently dropped (FR-1204)
- Workflows: fallback paths emit `WarningRecord(reason="fallback")` (FR-1207)
- REST/MCP: `warnings` list in response envelopes contains `WarningRecord` dicts not bare strings
- All existing tests must remain green; add targeted FR-1200 tests

Deliverable: `pytest tests/test_error_framework.py` passes; all modules emit structured records.

---

## T03 — Cross-reference support (FR-531, FR-540)

```task
id: MRKD-WP-0003-T03
status: done
priority: high
state_hub_task_id: 0bb9c7ce-5eb8-4997-833f-c801e37f282c
```

Implement cross-reference round-trip support for LEVEL3 projects.

- Markdown syntax: `[text][anchor]` and `{#anchor}` label declarations
- Builder: heading labels `{#anchor}` → DOCX bookmarks; cross-ref links → DOCX hyperlinks
  pointing to bookmarks (FR-531)
- Importer: DOCX bookmarks → `{#anchor}` heading labels; bookmark hyperlinks → `[text][anchor]`
- Differ: detect resolved / preserved / degraded / broken cross-refs and report (FR-540);
  broken = target bookmark missing in re-imported result
- Unit tests covering: single-file xref round-trip, broken xref detection, multi-ref documents

Deliverable: `pytest tests/test_level3_xref.py` passes.

---

## T04 — Numbered figures support (FR-532, FR-541)

```task
id: MRKD-WP-0003-T04
status: done
priority: high
state_hub_task_id: af6b82b7-da44-4ef8-8976-6e40fee5f73c
```

Implement numbered figure round-trip for LEVEL3 projects.

- Markdown syntax: `![Caption text](path/to/image.png){#fig:label}` — image with
  captioned label as figure declaration
- Builder: render as DOCX image + caption paragraph with auto-numbering style
  (`Figure N — Caption text`) (FR-532)
- Importer: detect captioned image paragraphs → restore `![Caption](path){#fig:label}`
- Differ: report whether figure numbering and identity remained coherent (FR-541);
  degraded = caption present but number changed; broken = figure missing
- Unit tests: single figure, multiple figures, figure identity coherence check

Deliverable: `pytest tests/test_level3_figures.py` passes.

---

## T05 — Auto-diagram support (FR-533, FR-534)

```task
id: MRKD-WP-0003-T05
status: done
priority: medium
state_hub_task_id: 3700e0e4-cc3b-4ef3-8b85-6cef24c35fc0
```

Implement diagram source declaration support for LEVEL3 projects.

- Markdown syntax: fenced code blocks with info string `mermaid`, `graphviz`, `plantuml`
- Builder: if external renderer available → render to PNG and embed as DOCX image;
  if unavailable → embed source as verbatim code block + emit processor-dependency
  disclosure warning (FR-538); preserve source-intent link as DOCX alt-text (FR-534)
- Importer: detect diagram-source alt-text markers → restore fenced block with original source
- No silent discard of diagram source (FR-1205)
- Unit tests: source-only path (no renderer), round-trip source preservation

Deliverable: `pytest tests/test_level3_diagrams.py` passes.

---

## T06 — Bibliography & citation support (FR-535, FR-536, FR-542)

```task
id: MRKD-WP-0003-T06
status: done
priority: medium
state_hub_task_id: 7c0acbd3-65f0-440b-9ad4-a5f09fabef3c
```

Implement bibliography and citation round-trip for LEVEL3 projects.

- Markdown syntax: `[@key]` inline citation; `## References` section with structured
  entries (`- [@key]: Author. *Title*. Year.`)
- Builder: inline citations → DOCX citation markers; References section →
  DOCX bibliography section with matching entries (FR-535)
- Importer: DOCX citation markers → `[@key]`; bibliography section →
  `## References` with entries; unresolvable citations → `WarningRecord(reason="citation-ambiguity")` (FR-536, FR-542)
- Differ: detect citation loss, marker-entry mismatches, and bibliography ambiguity (FR-542)
- Unit tests: single citation, multi-citation document, unresolvable citation warning

Deliverable: `pytest tests/test_level3_bibliography.py` passes.

---

## T07 — LEVEL3 regression test corpus & harness

```task
id: MRKD-WP-0003-T07
status: done
priority: medium
state_hub_task_id: b26241b9-0fff-45a2-a95c-dd886a449038
```

Extend the regression harness with a LEVEL3 test corpus so every advanced feature
is covered by an end-to-end roundtrip test.

- Add `tests/regression/level3/` with corpus Markdown source files:
  - `xref_document.md` — headings with anchors, cross-references
  - `figures_document.md` — multiple numbered figures
  - `diagrams_document.md` — mermaid and graphviz fenced blocks
  - `bibliography_document.md` — inline citations + References section
  - `combined_document.md` — all LEVEL3 constructs in one document
- `tests/regression/test_level3_roundtrip.py` — full roundtrip for each corpus file
  under `feature_level: level3`; asserts no unexpected breakage in differs
- All LEVEL1 regression tests must remain green (non-regression gate)
- `markidocx test` CLI command executes both LEVEL1 and LEVEL3 corpus

Deliverable: `pytest tests/regression/test_level3_roundtrip.py` passes; full suite
remains at 0 failures.

---

## How to Work

- Stay strictly within the scope of this workplan
- Work through tasks in priority order (high → medium → low)
- T01 must be complete before T03–T06 (gates LEVEL3 processing paths)
- T02 can be worked in parallel with T01 (cross-cutting, no dependency)
- Use TDD: write failing test, make it pass, then refactor
- Consult FRS v0.2 sections 7.5.2 and 7.12 for requirement details

## Updating Task Status

```
status: todo        →  status: in_progress   (when you start it)
status: in_progress →  status: done          (when verified complete)
```

When every task is `done`, set the frontmatter `status: done`.

## Success Criteria

Before marking the workplan done:

1. Every task block has `status: done`
2. Workplan frontmatter `status: done`
3. Full test suite passes with no failures (LEVEL1 + LEVEL3)
4. `ruff check` and `mypy` clean
5. CLAUDE.md implementation table updated