generated from coulomb/repo-seed
chore: add workplan MRKD-WP-0003 — LEVEL3 Advanced Features & Error Hardening
7 tasks covering FR-531–542 (cross-refs, numbered figures, auto-diagrams, bibliography) and FR-1201–1210 (error & warning framework). Workstream registered in State Hub (b04fe706). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
228
workplans/MRKD-WP-0003-level3-advanced-features.md
Normal file
228
workplans/MRKD-WP-0003-level3-advanced-features.md
Normal file
@@ -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: `{#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: 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
|
||||
Reference in New Issue
Block a user