marki-docx/workplans/MRKD-WP-0003-level3-advanced-features.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-0003	workplan	markitect	marki-docx	done	b04fe706-6e4e-48a8-b6c1-194d9e308215	2026-03-17	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)

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)

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)

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)

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)

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)

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

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