generated from coulomb/repo-seed
Bernd Worsch
ac442ea41f
Implements full LEVEL3 feature set: cross-references (xref.py), numbered figures (figures.py), auto-diagrams (diagrams.py), bibliography/citations (bibliography.py), LEVEL3 capability detection (level3.py), and structured error/warning records (errors.py). Builder, importer, and differ updated for LEVEL3 round-trip support. REST and MCP interfaces updated with structured warning records. 259 tests passing. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
229 lines
8.6 KiB
Markdown
229 lines
8.6 KiB
Markdown
---
|
||
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: `{#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 `{#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
|