diff --git a/workplans/MRKD-WP-0003-level3-advanced-features.md b/workplans/MRKD-WP-0003-level3-advanced-features.md new file mode 100644 index 0000000..8619675 --- /dev/null +++ b/workplans/MRKD-WP-0003-level3-advanced-features.md @@ -0,0 +1,228 @@ +--- +id: MRKD-WP-0003 +type: workplan +domain: markitect +repo: marki-docx +status: active +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: todo +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: todo +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: todo +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: todo +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: todo +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: todo +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: todo +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