From c6dfc9b1721108b24926203b45214843e75bef1a Mon Sep 17 00:00:00 2001 From: tegwick Date: Sat, 14 Mar 2026 18:18:54 +0100 Subject: [PATCH] chore: workplan MRKD-WP-0001 + improved CLAUDE.md; document next steps MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - workplans/MRKD-WP-0001-foundation-level1.md: 8-task workplan for Foundation & LEVEL1 Core (T01 scaffolding through T08 e2e harness) - CLAUDE.md: added Planned Architecture section (interface table, FR domain map, key concepts, round-trip data flow) and Development Commands stubs derived from FRS v0.2 - problems/next-steps-2026-03-14.md: implementation guide for next session — task order, dep list, state-hub task UUIDs, quality gates No code implemented yet; workstream registered in State Hub. Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 88 +- problems/next-steps-2026-03-14.md | 76 + pyproject.toml | 53 + ...unctionalRequirementsSpecification_v0.1.md | 737 +++++++++ ...unctionalRequirementsSpecification_v0.2.md | 1191 ++++++++++++++ ...rkiDocxProductRequirementsDocument_v0.1.md | 391 +++++ specs/MarkiDocxUseCaseCatalog_v0.1.md | 1412 +++++++++++++++++ src/markidocx/__init__.py | 3 + src/markidocx/cli.py | 261 +++ tests/__init__.py | 0 tests/conftest.py | 63 + workplans/MRKD-WP-0001-foundation-level1.md | 191 +++ 12 files changed, 4465 insertions(+), 1 deletion(-) create mode 100644 problems/next-steps-2026-03-14.md create mode 100644 pyproject.toml create mode 100644 specs/MarkiDocxFunctionalRequirementsSpecification_v0.1.md create mode 100644 specs/MarkiDocxFunctionalRequirementsSpecification_v0.2.md create mode 100644 specs/MarkiDocxProductRequirementsDocument_v0.1.md create mode 100644 specs/MarkiDocxUseCaseCatalog_v0.1.md create mode 100644 src/markidocx/__init__.py create mode 100644 src/markidocx/cli.py create mode 100644 tests/__init__.py create mode 100644 tests/conftest.py create mode 100644 workplans/MRKD-WP-0001-foundation-level1.md diff --git a/CLAUDE.md b/CLAUDE.md index e122f74..3cb0fdb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,6 @@ # CLAUDE.md -This file provides guidance to Claude Code when working in this repository. +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## What This Repo Is @@ -18,6 +18,92 @@ Key artefacts already in this repo: --- +## Planned Architecture + +markidocx is a **conversion pipeline** with three delivery interfaces over a shared functional core. + +### Interfaces +| Interface | Purpose | +|-----------|---------| +| CLI | Local document workflows (`markidocx build`, `import`, `validate`, `compare`) | +| REST service | Automation / pipeline integration | +| MCP tools | Agent-accessible operations (same functional surface as CLI/REST) | + +All three interfaces expose the same functional model — no interface-specific logic should live outside its adapter layer. + +### Core Functional Domains (from FRS) +| FR group | Domain | +|----------|--------| +| FR-100 | Project & manifest management | +| FR-200 | Build / export (Markdown → DOCX) | +| FR-300 | Import / round-trip (DOCX → Markdown) | +| FR-400 | Multi-file composition & redistribution | +| FR-500 | Feature-level enforcement (LEVEL1 / LEVEL3) | +| FR-600 | Template & style family management | +| FR-700 | Validation & drift analysis | +| FR-1100 | Test & regression | +| FR-1300 | Composite workflow orchestration | +| FR-1400 | Evidence & report assembly | + +### Key Concepts +- **Project manifest** — declares source files, feature level, and template/style family; drives all operations +- **Feature levels** — LEVEL1 (headings, lists, tables, footnotes, images, links); LEVEL3 adds cross-refs, numbered figures, auto-diagrams, bibliography +- **Document families** — three built-in: `article`, `book`, `website`; extensible via registration +- **Source mapping** — multi-file imports must redistribute content back to origin files; fallback produces a merged single file +- **Drift detection** — structural diff between original Markdown and re-imported result; reported as inspectable evidence + +### Round-trip data flow +``` +manifest + Markdown sources + ↓ FR-100 (resolve project) + ↓ FR-200 (compose + export → DOCX) + [Word editorial review] + ↓ FR-300 (import DOCX → Markdown) + ↓ FR-400 (redistribute to source files) + ↓ FR-700 (validate + drift report) +evidence artefacts +``` + +--- + +## Development Commands + +> **Pre-implementation note:** No code exists yet. Commands below describe the intended interface; update this section as the package takes shape. + +```bash +# Install in editable mode (once pyproject.toml exists) +pip install -e ".[dev]" + +# Run tests +pytest + +# Run a single test file +pytest tests/path/to/test_file.py + +# Lint +ruff check . + +# Type-check +mypy src/ + +# Start REST service (dev mode) +markidocx serve --dev + +# CLI: build a document project +markidocx build + +# CLI: import an edited DOCX +markidocx import + +# CLI: compare baseline vs re-import +markidocx compare + +# CLI: run end-to-end regression +markidocx test +``` + +--- + ## Custodian State Hub Integration This project is tracked as the **markitect** domain in the Custodian State Hub. diff --git a/problems/next-steps-2026-03-14.md b/problems/next-steps-2026-03-14.md new file mode 100644 index 0000000..ba5b3c4 --- /dev/null +++ b/problems/next-steps-2026-03-14.md @@ -0,0 +1,76 @@ +# Next Steps — 2026-03-14 + +## Status +Ralph loop iteration 1 was interrupted before implementation began. +No code has been written yet — repo contains only specs, workplan, and CLAUDE.md. + +## What needs to happen (in order) + +### T01 — Project scaffolding +Create `pyproject.toml` (name: markidocx, Python >=3.11), `src/markidocx/__init__.py`, +`src/markidocx/cli.py` (typer stub), `tests/__init__.py`, `tests/conftest.py`. + +Key deps: python-docx, pyyaml, typer, rich, mistune +Dev deps: pytest, pytest-cov, ruff, mypy, types-PyYAML + +Install: `pip install -e ".[dev]"` + +### T02 — Manifest model (`src/markidocx/manifest.py`) +YAML schema: project (name, feature_level, family), sources (list of paths), output.dir, metadata. +Implement: load_manifest(), Manifest dataclass, ManifestError, resolution status reporting. +Tests: `tests/test_manifest.py` + +### T03 — LEVEL1 build (`src/markidocx/builder.py`) +Markdown → DOCX using python-docx + mistune. +LEVEL1 elements: headings, lists, tables, footnotes, images, links, bold/italic. +BuildResult dataclass. Embed source-boundary XML part for multi-file round-trips. +Tests: `tests/test_builder.py` + +### T05 — Template families (`src/markidocx/templates.py`) +Three families: article, book, website — created programmatically with python-docx, +stored as package data in `src/markidocx/templates/`. +FamilyRegistry with list/get/register. +Tests: `tests/test_templates.py` + +### T04 — LEVEL1 import (`src/markidocx/importer.py`) +DOCX → Markdown using python-docx. Redistribute to source files using embedded boundary XML. +Fallback: single merged output. +ImportResult dataclass. +Tests: `tests/test_importer.py` + +### T06 — Drift detection (`src/markidocx/differ.py`) +Structural diff between original and re-imported Markdown. +DriftReport dataclass (preserved/degraded/broken/unsupported). +Tests: `tests/test_differ.py` + +### T07 — CLI (`src/markidocx/cli.py`) +Typer commands: build, import, compare, validate, template list/register. +--json flag, exit codes 0/1/2. + +### T08 — E2E harness (`tests/test_e2e.py`) +Round-trip the spec files through build→import→compare. +Smoke test each family. Assert zero drift on headings/lists. + +## Architecture decisions to write +- `architecture/ADR-002-python-docx-as-conversion-engine.md` +- `architecture/ADR-003-manifest-yaml-schema.md` + +## State Hub task IDs (mark done as each task completes) +- T01: 5dd0e377-2a4e-4ddd-a6fa-aeb097ead292 +- T02: d381a578-821a-44f0-b1a2-5254966aae48 +- T03: 2c466852-d136-48cf-ba53-8c999f11527e +- T04: 117a5de0-eeef-4358-8c78-fed26ae55f2b +- T05: 3d10a43b-301d-4717-9ab4-f43851058c3f +- T06: 0390f7d3-a9c3-4cac-a295-303adfe82960 +- T07: 2e455d87-9044-411e-91c7-3a512488904a +- T08: ca3ecede-aef3-48b0-b21b-2b9f59167cb5 + +Workstream ID: de855681-7ce0-4ace-b283-ec61f7557066 +Topic ID: 5571d954-0d30-4950-980d-7bcaaad8e3e2 + +## Quality gates before marking done +- `ruff check src/ tests/` — no errors +- `mypy src/markidocx/` — no errors +- `pytest tests/ -v` — all pass +- `markidocx --help` works +- `markidocx build` + `markidocx validate` work on a simple manifest diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..37fe541 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,53 @@ +[build-system] +requires = ["setuptools>=68", "wheel"] +build-backend = "setuptools.build_meta" + +[project] +name = "markidocx" +version = "0.1.0" +description = "Markdown ↔ DOCX round-trip editing system" +requires-python = ">=3.11" +dependencies = [ + "python-docx>=1.1.0", + "pyyaml>=6.0", + "typer>=0.12", + "rich>=13.0", + "mistune>=3.0", +] + +[project.optional-dependencies] +dev = [ + "pytest>=8.0", + "pytest-cov>=5.0", + "ruff>=0.4", + "mypy>=1.10", + "types-PyYAML>=6.0", +] + +[project.scripts] +markidocx = "markidocx.cli:app" + +[tool.setuptools.packages.find] +where = ["src"] + +[tool.setuptools.package-data] +markidocx = ["templates/*.docx"] + +[tool.ruff] +line-length = 100 +target-version = "py311" + +[tool.ruff.lint] +select = ["E", "F", "I", "UP", "B", "SIM"] +ignore = ["E501"] + +[tool.mypy] +python_version = "3.11" +strict = false +warn_return_any = true +warn_unused_configs = true +ignore_missing_imports = true + +[tool.pytest.ini_options] +testpaths = ["tests"] +addopts = "-v" diff --git a/specs/MarkiDocxFunctionalRequirementsSpecification_v0.1.md b/specs/MarkiDocxFunctionalRequirementsSpecification_v0.1.md new file mode 100644 index 0000000..7f15312 --- /dev/null +++ b/specs/MarkiDocxFunctionalRequirementsSpecification_v0.1.md @@ -0,0 +1,737 @@ +# FRS + +*Functional Requirements Specification* + +# Functional Requirements Specification: markidocx + +## 1. Definition + +This Functional Requirements Specification defines the externally observable behaviors and required functions of **markidocx**, a system for controlled **Markdown ↔ DOCX round-trip editing**. + +The FRS specifies what markidocx must do from the perspective of users, external systems, and exposed interfaces. It defines required functions for: + +* document build and export +* document import and reconstitution +* multi-file composition +* template and style management +* feature-level document processing +* validation and drift reporting +* local CLI usage +* REST-based service interaction +* MCP-based tool interaction +* end-to-end regression execution + +This FRS is derived from the markidocx PRD and serves as the binding functional contract for implementation and acceptance. + +--- + +## 2. Context + +markidocx is intended to support documentation workflows in which: + +* structured content is maintained in Markdown +* editorial review is performed in Microsoft Word +* document generation must be repeatable and inspectable +* multiple stakeholders and systems interact with the same documentation assets + +The system acts as a functional bridge between: + +* canonical Markdown source documents +* Word-based review artifacts +* automated documentation pipelines +* external tools and agents + +Functionally, the system must allow content to move between these contexts while preserving supported structure and surfacing any drift or ambiguity introduced during the process. + +--- + +## 3. Core Concepts + +### 3.1 System Function + +A system function is a user-visible or interface-visible capability the system provides, such as building a DOCX artifact, importing an edited document, or validating a template registration. + +### 3.2 Externally Observable Behavior + +Externally observable behavior includes all results visible through the CLI, REST interface, MCP interface, output artifacts, reports, and return statuses. + +### 3.3 Requirement Statement + +Each requirement in this document is written as a declarative, testable statement describing required system behavior. + +### 3.4 Input–Output Relationship + +markidocx receives manifests, Markdown sources, templates, styles, DOCX files, and configuration inputs and produces artifacts, reports, validation outcomes, and structured metadata. + +### 3.5 Traceability + +The requirements in this FRS are intended to trace back to the markidocx PRD and forward into implementation, interface contracts, and validation suites. + +--- + +## 4. Scope and Non-Scope + +### In Scope + +This FRS covers: + +* functional system behavior +* user-facing and interface-facing commands and operations +* supported document processing behavior +* interface-level interactions through CLI, REST, and MCP +* functional handling of templates, styles, manifests, and artifacts +* conditions under which functions succeed, warn, or fail + +### Out of Scope + +This FRS does not define: + +* internal architecture +* code organization +* algorithms or parser strategies +* storage implementation +* UI layout +* deployment topology +* performance or security design except where behaviorally relevant + +--- + +## 5. System Overview + +markidocx shall provide a functional workflow in which a user or external system can: + +1. define a document project using Markdown sources and a manifest +2. compose one or more Markdown files into a document model +3. export that document into DOCX using a selected template/style family +4. import an edited DOCX back into Markdown form +5. validate compatibility and structural integrity +6. detect and report drift between baseline and re-imported forms +7. manage template/style families +8. access the same capabilities locally, via service calls, or through MCP tools +9. run end-to-end tests using the latest stable markidocx documentation corpus + +--- + +## 6. Functional Requirements Structure + +Requirements are grouped into the following domains: + +* FR-100 Project and manifest management +* FR-200 Build and export +* FR-300 Import and round-trip processing +* FR-400 Multi-file document handling +* FR-500 Feature level support +* FR-600 Template and style management +* FR-700 Validation and drift analysis +* FR-800 CLI functions +* FR-900 REST service functions +* FR-1000 MCP functions +* FR-1100 Test and regression functions +* FR-1200 Error and warning behavior + +--- + +# 7. Functional Requirements + +## 7.1 Project and Manifest Management + +### FR-101 Project Manifest Recognition + +The system shall accept a project definition that identifies the document project, its source files, document type, feature level, and associated template/style selections. + +### FR-102 Manifest Validation + +The system shall determine whether a provided project manifest is syntactically and functionally valid. + +### FR-103 Missing Resource Detection + +The system shall report an error when a manifest references a source, asset, bibliography, template, or style that is not available. + +### FR-104 Project Inspection + +The system shall provide a way to inspect the resolved project configuration, including source ordering, selected feature level, template selection, and derived document metadata. + +### FR-105 Project Capability Disclosure + +The system shall expose the effective capabilities of a project as derived from the manifest and registered feature support. + +### FR-106 Unsupported Manifest Configuration Detection + +The system shall reject or warn on manifest settings that are inconsistent with supported system behavior. + +--- + +## 7.2 Build and Export + +### FR-201 Build Invocation + +The system shall allow a user or external client to request document build/export for a defined project. + +### FR-202 Markdown Composition + +The system shall compose the project’s declared Markdown sources into a buildable document representation. + +### FR-203 DOCX Export + +The system shall generate a DOCX artifact from a valid project when DOCX output is requested. + +### FR-204 Template Application + +The system shall apply the selected DOCX template family during DOCX generation. + +### FR-205 Style Selection + +The system shall associate the selected style family with the generated output where relevant to the output mode. + +### FR-206 Asset Inclusion + +The system shall include referenced images and other supported assets in the exported document where the asset is valid and resolvable. + +### FR-207 Metadata Propagation + +The system shall propagate supported document metadata from project inputs into the generated document. + +### FR-208 Build Result Reporting + +The system shall return a structured build result indicating success, warnings, or failure and identify generated artifacts. + +### FR-209 Deterministic Build Result Disclosure + +The system shall provide build output metadata sufficient for later validation and comparison. + +--- + +## 7.3 Import and Round-Trip Processing + +### FR-301 DOCX Import Invocation + +The system shall allow a user or external client to submit a DOCX document for import into Markdown-compatible project form. + +### FR-302 Project-Aware Import + +The system shall import DOCX content in the context of a specified project configuration when such context is provided. + +### FR-303 Markdown Reconstitution + +The system shall produce Markdown output from the imported DOCX for supported constructs. + +### FR-304 Structural Preservation + +The system shall preserve supported document structure during import within the bounds of the selected feature level. + +### FR-305 Source Mapping Use + +When project source mapping is available, the system shall use it to associate imported content with original source boundaries. + +### FR-306 Import Result Reporting + +The system shall report the result of an import operation, including generated outputs, warnings, and identified ambiguities. + +### FR-307 Unsupported Construct Reporting + +The system shall explicitly report Word constructs that cannot be safely mapped into supported Markdown representation. + +### FR-308 Re-import Equivalence Support + +The system shall support round-trip workflows in which exported DOCX documents can be re-imported into semantically equivalent Markdown representations, subject to supported feature classes and accepted normalization. + +--- + +## 7.4 Multi-File Document Handling + +### FR-401 Multi-File Source Declaration + +The system shall support projects consisting of multiple Markdown source files. + +### FR-402 Ordered Composition + +The system shall preserve declared source ordering when composing a multi-file document. + +### FR-403 Whole-Document Export + +The system shall support export of a multi-file project into a single reviewable document artifact. + +### FR-404 Source-Origin Awareness + +The system shall maintain source-origin information sufficient to support round-trip handling of multi-file documents. + +### FR-405 Source Redistribution + +The system shall support redistribution of imported content back into source-aligned outputs when source mapping information is available. + +### FR-406 Fallback Import Form + +When source redistribution cannot be completed safely, the system shall provide a valid merged Markdown result and indicate the fallback condition. + +### FR-407 Section Boundary Integrity Reporting + +The system shall report when imported edits cause ambiguity or breakage at tracked source or section boundaries. + +--- + +## 7.5 Feature Level Support + +## 7.5.1 LEVEL1 + +### FR-501 Heading Support + +The system shall export and import heading structures and preserve supported heading hierarchy. + +### FR-502 List Support + +The system shall export and import ordered and unordered lists and preserve list structure within supported cases. + +### FR-503 Table Support + +The system shall export and import supported table structures. + +### FR-504 Footnote Support + +The system shall export and import footnotes and preserve their association with referencing content. + +### FR-505 Image Support + +The system shall export and import supported images and preserve image references and associated descriptive metadata where available. + +### FR-506 Link Support + +The system shall export and import links and preserve supported link targets and visible text. + +## 7.5.2 LEVEL3 + +### FR-531 Cross-Reference Support + +The system shall support export and import workflows for supported cross references between labeled content elements. + +### FR-532 Numbered Figure Support + +The system shall support export of figures with captions and numbering and preserve figure identity sufficiently for supported round-trip usage. + +### FR-533 Automatic Diagram Support + +The system shall support diagrams derived from source declarations as part of document build/export workflows. + +### FR-534 Diagram Intent Preservation + +The system shall preserve the connection between diagram source intent and rendered output within the managed workflow. + +### FR-535 Bibliography Support + +The system shall support bibliography-aware document generation from structured citation inputs. + +### FR-536 Citation Preservation + +The system shall preserve supported citation semantics during round-trip processing or report when ambiguity prevents safe preservation. + +### FR-537 Feature-Level Compatibility Disclosure + +The system shall disclose whether a project, template family, or processing path supports LEVEL1 only or LEVEL3. + +--- + +## 7.6 Template and Style Management + +### FR-601 Built-In Family Availability + +The system shall provide three built-in document families named: + +* article +* book +* website + +### FR-602 Family Metadata Disclosure + +The system shall provide discoverable metadata for each available template/style family. + +### FR-603 Template Listing + +The system shall provide a way to list available template families. + +### FR-604 Style Listing + +The system shall provide a way to list available style families. + +### FR-605 Template Registration + +The system shall allow registration of an additional document template. + +### FR-606 Style Registration + +The system shall allow registration of an additional style definition. + +### FR-607 Paired Family Registration + +The system shall allow registration of an additional template/style family association. + +### FR-608 Registration Validation + +The system shall validate a proposed registration and report whether it is acceptable. + +### FR-609 Compatibility Declaration + +The system shall associate each template/style family with declared capability metadata, including applicable document types and feature-level support. + +### FR-610 Family Resolution + +The system shall resolve a family reference in a project to the corresponding registered template/style resources. + +--- + +## 7.7 Validation and Drift Analysis + +### FR-701 Validation Invocation + +The system shall allow validation of a project without performing a full build or import. + +### FR-702 Validation Scope + +The system shall validate manifest integrity, referenced resources, selected feature level, and template/style compatibility. + +### FR-703 Build Preconditions Reporting + +The system shall report whether a project is functionally ready for build. + +### FR-704 Drift Comparison + +The system shall allow comparison of baseline and imported Markdown representations. + +### FR-705 Drift Classification + +The system shall classify detected differences into at least the following functional categories: + +* cosmetic +* normalized +* structural +* unsupported or ambiguous +* fatal + +### FR-706 Structural Drift Detection + +The system shall identify structural changes affecting supported document semantics. + +### FR-707 Cross-Reference Integrity Check + +The system shall detect and report broken or unresolved supported cross references. + +### FR-708 Figure Integrity Check + +The system shall detect and report supported figure numbering or identity inconsistencies. + +### FR-709 Bibliography Integrity Check + +The system shall detect and report unresolved bibliography or citation issues in supported workflows. + +### FR-710 Validation Result Output + +The system shall produce validation and drift results in a machine-consumable form and a human-consumable form. + +--- + +## 7.8 CLI Functions + +### FR-801 Local CLI Availability + +The system shall provide a local command-line interface for core markidocx functions. + +### FR-802 CLI Build Command + +The CLI shall provide a command to build/export a project. + +### FR-803 CLI Import Command + +The CLI shall provide a command to import DOCX content into project-compatible Markdown outputs. + +### FR-804 CLI Validate Command + +The CLI shall provide a command to validate a project. + +### FR-805 CLI Diff Command + +The CLI shall provide a command to compare round-trip outputs or equivalent document states. + +### FR-806 CLI Inspect Command + +The CLI shall provide a command to inspect resolved project information. + +### FR-807 CLI Template Listing Command + +The CLI shall provide a command to list template families. + +### FR-808 CLI Style Listing Command + +The CLI shall provide a command to list styles or style families. + +### FR-809 CLI Registration Commands + +The CLI shall provide commands to register templates, styles, or families. + +### FR-810 CLI Test Command + +The CLI shall provide a command to execute the defined test suite or end-to-end validation workflow. + +### FR-811 CLI Exit Status Behavior + +The CLI shall return success, warning, or failure outcomes through distinguishable exit behavior and output. + +### FR-812 CLI Structured Output + +The CLI shall support a structured output mode for machine consumption. + +--- + +## 7.9 REST Service Functions + +### FR-901 REST Service Availability + +The system shall provide a REST-accessible service exposing core markidocx functions. + +### FR-902 REST Project Validation + +The service shall allow clients to submit a project for validation and receive a structured result. + +### FR-903 REST Build + +The service shall allow clients to request document build/export and retrieve resulting artifacts and reports. + +### FR-904 REST Import + +The service shall allow clients to submit DOCX content for import and receive generated Markdown-compatible outputs and reports. + +### FR-905 REST Drift Comparison + +The service shall allow clients to request drift analysis between supplied or project-associated document states. + +### FR-906 REST Template Listing + +The service shall provide an endpoint for listing available template families. + +### FR-907 REST Style Listing + +The service shall provide an endpoint for listing available styles or style families. + +### FR-908 REST Registration + +The service shall allow submission of additional template/style registrations and return validation results. + +### FR-909 REST Capability Inspection + +The service shall provide a way to retrieve supported capability and feature-level information. + +### FR-910 REST Health Disclosure + +The service shall provide a machine-readable health/status response. + +### FR-911 REST Version Disclosure + +The service shall provide a machine-readable version response. + +### FR-912 REST Structured Responses + +The service shall return structured responses that identify status, outputs, warnings, and errors. + +--- + +## 7.10 MCP Functions + +### FR-1001 MCP Availability + +The system shall provide an MCP-compatible interface exposing markidocx capabilities to agentic clients. + +### FR-1002 MCP Template Discovery + +The MCP interface shall expose a tool or equivalent operation to list available template families. + +### FR-1003 MCP Style Discovery + +The MCP interface shall expose a tool or equivalent operation to list available style families. + +### FR-1004 MCP Project Validation + +The MCP interface shall expose a tool or equivalent operation to validate a project. + +### FR-1005 MCP Project Inspection + +The MCP interface shall expose a tool or equivalent operation to inspect a project. + +### FR-1006 MCP Build + +The MCP interface shall expose a tool or equivalent operation to build/export a project. + +### FR-1007 MCP Import + +The MCP interface shall expose a tool or equivalent operation to import DOCX content. + +### FR-1008 MCP Drift Comparison + +The MCP interface shall expose a tool or equivalent operation to compare round-trip states. + +### FR-1009 MCP Test Execution + +The MCP interface shall expose a tool or equivalent operation to run end-to-end tests. + +### FR-1010 MCP Version Disclosure + +The MCP interface shall expose a tool or equivalent operation to disclose system version information. + +### FR-1011 MCP Resource Exposure + +The MCP interface shall expose relevant machine-consumable resources for manifests, capabilities, template metadata, style metadata, and current documentation corpus metadata. + +--- + +## 7.11 Test and Regression Functions + +### FR-1101 Stable Documentation Corpus + +The system shall maintain the latest stable markidocx documentation as a managed documentation project. + +### FR-1102 Documentation-Based E2E Testing + +The system shall support execution of end-to-end validation using the latest stable markidocx documentation as the test corpus. + +### FR-1103 Round-Trip Regression Execution + +The system shall support a test flow in which the documentation corpus is built, exported, imported, and compared. + +### FR-1104 Template Coverage in E2E Testing + +The system shall support end-to-end testing against the built-in article, book, and website families where applicable. + +### FR-1105 Feature-Level Coverage in E2E Testing + +The system shall support execution of tests covering LEVEL1 and LEVEL3 behavior as represented in the stable documentation corpus. + +### FR-1106 Test Result Reporting + +The system shall provide a report identifying whether regression and end-to-end validation passed, warned, or failed. + +--- + +## 7.12 Error and Warning Behavior + +### FR-1201 Explicit Failure Reporting + +The system shall explicitly report functional failures rather than silently omitting failed operations. + +### FR-1202 Explicit Warning Reporting + +The system shall explicitly report warnings when an operation completes with ambiguity, normalization, unsupported constructs, or partial degradation. + +### FR-1203 Unsupported Construct Visibility + +The system shall surface unsupported or ambiguous constructs in import, export, validation, or diff results. + +### FR-1204 Partial Result Disclosure + +When an operation produces partial results, the system shall indicate the partial nature of those results. + +### FR-1205 Non-Silent Degradation + +The system shall not silently discard known document constructs that fall outside supported round-trip behavior. + +--- + +# 8. Functional Use Cases + +## UC-01 Single-File Round-Trip + +A user provides a single Markdown project, builds DOCX, edits the DOCX, imports it back, and receives an updated Markdown result plus drift report. + +## UC-02 Multi-File Review Workflow + +A user provides a multi-file project, exports one DOCX for review, imports the reviewed DOCX, and receives redistributed or merged Markdown outputs with section mapping status. + +## UC-03 Template Switching + +A user builds the same content using article, book, and website families and receives corresponding output artifacts without changing the source content. + +## UC-04 Validation Before Build + +A user validates a project and receives confirmation of readiness or a list of blocking issues. + +## UC-05 External Automation + +An external system submits a project to the REST service for build, import, or comparison and receives structured results. + +## UC-06 Agentic Interaction + +An MCP client discovers available templates, validates a project, triggers a build, and retrieves validation outcomes. + +## UC-07 Product Self-Test + +A release process runs end-to-end tests against the latest stable markidocx documentation and records regression status. + +--- + +# 9. Functional Constraints + +### FC-01 Supported Semantic Envelope + +The system shall only claim preservation for constructs within the declared supported feature levels and managed workflow boundaries. + +### FC-02 Project-Scoped Operation + +Build, import, validation, and drift functions shall operate in relation to an explicit project context or explicitly supplied artifact set. + +### FC-03 Family-Scoped Capability + +Template/style application shall be constrained by the declared capabilities of the selected family. + +### FC-04 Fallback Disclosure + +Whenever the system falls back from source-aligned redistribution to merged or degraded output, it shall disclose that fallback. + +--- + +# 10. Acceptance-Oriented Functional Summary + +markidocx shall be considered functionally conformant to this FRS when it can, at minimum: + +1. accept and validate a project manifest +2. compose single-file and multi-file Markdown documents +3. export DOCX using built-in document families +4. import edited DOCX back into Markdown-compatible outputs +5. support all declared LEVEL1 functions +6. support declared LEVEL3 functions for managed cases +7. detect and classify round-trip drift +8. expose core functions through CLI +9. expose core functions through REST +10. expose core functions through MCP +11. register additional templates and styles +12. run end-to-end tests using the latest stable markidocx documentation corpus + +--- + +# 11. Related Artifacts + +This FRS is expected to relate to: + +* PRD: markidocx +* Non-Functional Requirements document +* API/interface contracts +* schema definitions for manifests and registrations +* test specifications +* acceptance criteria catalog +* system design specification +* architecture decision records + +--- + +# 12. Appendix: Suggested Requirement Trace Anchors + +A minimal traceability map should connect: + +* PRD product goals → FRS requirement groups +* FRS requirement IDs → interface contracts +* FRS requirement IDs → acceptance tests +* FRS requirement IDs → regression scenarios + +Example trace anchors: + +* PRD Round-Trip Editing → FR-201 to FR-308 +* PRD Multi-File Composition → FR-401 to FR-407 +* PRD Built-In Families → FR-601 to FR-610 +* PRD CLI/REST/MCP accessibility → FR-801 to FR-1011 +* PRD E2E documentation corpus → FR-1101 to FR-1106 + +xxx diff --git a/specs/MarkiDocxFunctionalRequirementsSpecification_v0.2.md b/specs/MarkiDocxFunctionalRequirementsSpecification_v0.2.md new file mode 100644 index 0000000..8e91cd0 --- /dev/null +++ b/specs/MarkiDocxFunctionalRequirementsSpecification_v0.2.md @@ -0,0 +1,1191 @@ +# FRS + +*Functional Requirements Specification* + +# Functional Requirements Specification: markidocx + +**Version:** v0.2 +**Status:** Draft +**Supersedes:** Previous draft FRS for markidocx +**Related Artifacts:** PRD markidocx, UCC markidocx + +--- + +## 1. Definition + +This Functional Requirements Specification defines the externally observable behaviors and required functions of **markidocx**, a system for controlled **Markdown ↔ DOCX round-trip editing**. + +The FRS specifies what markidocx must do from the perspective of users, external systems, and exposed interfaces. It defines required functions for: + +* document build and export +* document import and reconstitution +* multi-file composition +* template and style management +* feature-level document processing +* validation and drift reporting +* local CLI usage +* REST-based service interaction +* MCP-based tool interaction +* end-to-end regression execution +* composite workflow execution +* evidence and report management + +This FRS is derived from the markidocx PRD and aligned with the markidocx UCC. It serves as the binding functional contract for implementation and acceptance. + +--- + +## 2. Context + +markidocx is intended to support documentation workflows in which: + +* structured content is maintained in Markdown +* editorial review is performed in Microsoft Word +* document generation must be repeatable and inspectable +* multiple stakeholders and systems interact with the same documentation assets + +The system acts as a functional bridge between: + +* canonical Markdown source documents +* Word-based review artifacts +* automated documentation pipelines +* external tools and agents + +Functionally, the system must allow content to move between these contexts while preserving supported structure and surfacing any drift or ambiguity introduced during the process. + +The UCC establishes actor-goal-centered workflows for this system. This FRS translates those workflows into precise functional expectations while remaining independent of architecture and implementation. + +--- + +## 3. Core Concepts + +### 3.1 System Function + +A system function is a user-visible or interface-visible capability the system provides, such as building a DOCX artifact, importing an edited document, validating a template registration, or assembling release evidence. + +### 3.2 Externally Observable Behavior + +Externally observable behavior includes all results visible through the CLI, REST interface, MCP interface, output artifacts, reports, and return statuses. + +### 3.3 Requirement Statement + +Each requirement in this document is written as a declarative, testable statement describing required system behavior. + +### 3.4 Input–Output Relationship + +markidocx receives manifests, Markdown sources, templates, styles, DOCX files, and configuration inputs and produces artifacts, reports, validation outcomes, and structured metadata. + +### 3.5 Traceability + +The requirements in this FRS are intended to trace back to the markidocx PRD and UCC and forward into implementation, interface contracts, and validation suites. + +### 3.6 Composite Workflow + +A composite workflow is a system-supported sequence of lower-level functions that together fulfill a meaningful actor goal, such as a full round-trip cycle or end-to-end regression run. + +### 3.7 Functional Evidence + +Functional evidence is an inspectable set of outputs produced by validation, build, import, comparison, or regression functions and usable for acceptance, audit, or release decisions. + +--- + +## 4. Scope and Non-Scope + +### In Scope + +This FRS covers: + +* functional system behavior +* user-facing and interface-facing commands and operations +* supported document processing behavior +* interface-level interactions through CLI, REST, and MCP +* functional handling of templates, styles, manifests, and artifacts +* conditions under which functions succeed, warn, fall back, or fail +* report and evidence generation as externally visible behavior +* workflow-level orchestration where exposed as a system function + +### Out of Scope + +This FRS does not define: + +* internal architecture +* code organization +* algorithms or parser strategies +* storage implementation +* UI layout +* deployment topology +* performance or security design except where behaviorally relevant + +--- + +## 5. System Overview + +markidocx shall provide a functional workflow in which a user or external system can: + +1. define a document project using Markdown sources and a manifest +2. compose one or more Markdown files into a document model +3. export that document into DOCX using a selected template/style family +4. import an edited DOCX back into Markdown form +5. validate compatibility and structural integrity +6. detect and report drift between baseline and re-imported forms +7. manage template/style families +8. access the same capabilities locally, via service calls, or through MCP tools +9. run end-to-end tests using the latest stable markidocx documentation corpus +10. invoke composite workflows for common round-trip scenarios +11. assemble inspectable evidence from validation and regression flows + +--- + +## 6. Functional Requirements Structure + +Requirements are grouped into the following domains: + +* FR-100 Project and manifest management +* FR-200 Build and export +* FR-300 Import and round-trip processing +* FR-400 Multi-file document handling +* FR-500 Feature level support +* FR-600 Template and style management +* FR-700 Validation and drift analysis +* FR-800 CLI functions +* FR-900 REST service functions +* FR-1000 MCP functions +* FR-1100 Test and regression functions +* FR-1200 Error and warning behavior +* FR-1300 Composite workflow functions +* FR-1400 Evidence and report management + +--- + +# 7. Functional Requirements + +## 7.1 Project and Manifest Management + +### FR-101 Project Manifest Recognition + +The system shall accept a project definition that identifies the document project, its source files, document type, feature level, and associated template/style selections. + +### FR-102 Manifest Validation + +The system shall determine whether a provided project manifest is syntactically and functionally valid. + +### FR-103 Missing Resource Detection + +The system shall report an error when a manifest references a source, asset, bibliography, template, or style that is not available. + +### FR-104 Project Inspection + +The system shall provide a way to inspect the resolved project configuration, including source ordering, selected feature level, template selection, and derived document metadata. + +### FR-105 Project Capability Disclosure + +The system shall expose the effective capabilities of a project as derived from the manifest and registered feature support. + +### FR-106 Unsupported Manifest Configuration Detection + +The system shall reject or warn on manifest settings that are inconsistent with supported system behavior. + +### FR-107 Project Context Reuse + +The system shall support reuse of a project definition across build, import, validation, comparison, and test operations. + +### FR-108 Project Context Identity + +The system shall expose sufficient project identity information to associate outputs and reports with the project from which they were derived. + +### FR-109 Project Resolution Status Reporting + +The system shall report whether project resolution completed successfully, completed with warnings, or failed. + +### FR-110 Project Input Scope Disclosure + +The system shall disclose which declared source files, assets, bibliography inputs, and family references are effectively in scope for a given project operation. + +--- + +## 7.2 Build and Export + +### FR-201 Build Invocation + +The system shall allow a user or external client to request document build/export for a defined project. + +### FR-202 Markdown Composition + +The system shall compose the project’s declared Markdown sources into a buildable document representation. + +### FR-203 DOCX Export + +The system shall generate a DOCX artifact from a valid project when DOCX output is requested. + +### FR-204 Template Application + +The system shall apply the selected DOCX template family during DOCX generation. + +### FR-205 Style Selection + +The system shall associate the selected style family with the generated output where relevant to the output mode. + +### FR-206 Asset Inclusion + +The system shall include referenced images and other supported assets in the exported document where the asset is valid and resolvable. + +### FR-207 Metadata Propagation + +The system shall propagate supported document metadata from project inputs into the generated document. + +### FR-208 Build Result Reporting + +The system shall return a structured build result indicating success, warnings, or failure and identify generated artifacts. + +### FR-209 Deterministic Build Result Disclosure + +The system shall provide build output metadata sufficient for later validation and comparison. + +### FR-210 Build Family Disclosure + +The system shall identify in the build result which template/style family was applied. + +### FR-211 Build Feature-Level Disclosure + +The system shall identify in the build result which feature level was applied. + +### FR-212 Alternate Output Compatibility Reporting + +When the same source is built under different compatible families, the system shall report each build result independently without implying semantic changes to the source content. + +### FR-213 Build Degradation Reporting + +When a build completes with degraded treatment of supported or optional content, the system shall disclose the degradation in the build result. + +### FR-214 Build Preconditions Reference + +The system shall allow build results to reference or embed the validation state relevant to the build where such state is available. + +--- + +## 7.3 Import and Round-Trip Processing + +### FR-301 DOCX Import Invocation + +The system shall allow a user or external client to submit a DOCX document for import into Markdown-compatible project form. + +### FR-302 Project-Aware Import + +The system shall import DOCX content in the context of a specified project configuration when such context is provided. + +### FR-303 Markdown Reconstitution + +The system shall produce Markdown output from the imported DOCX for supported constructs. + +### FR-304 Structural Preservation + +The system shall preserve supported document structure during import within the bounds of the selected feature level. + +### FR-305 Source Mapping Use + +When project source mapping is available, the system shall use it to associate imported content with original source boundaries. + +### FR-306 Import Result Reporting + +The system shall report the result of an import operation, including generated outputs, warnings, and identified ambiguities. + +### FR-307 Unsupported Construct Reporting + +The system shall explicitly report Word constructs that cannot be safely mapped into supported Markdown representation. + +### FR-308 Re-import Equivalence Support + +The system shall support round-trip workflows in which exported DOCX documents can be re-imported into semantically equivalent Markdown representations, subject to supported feature classes and accepted normalization. + +### FR-309 Import Context Disclosure + +The system shall disclose whether an import was performed with or without project-aware context. + +### FR-310 Redistribution Attempt Disclosure + +The system shall disclose whether source-aware redistribution was attempted during project-aware import. + +### FR-311 Import Mapping Status + +The system shall disclose whether imported content was source-aligned, partially source-aligned, merged as fallback, or imported without source alignment. + +### FR-312 Partial Import Result Reporting + +The system shall report when import produced only partial usable output. + +### FR-313 Import Preservation Scope Disclosure + +The system shall disclose which supported structures were preserved, degraded, unresolved, or unsupported in a given import operation. + +### FR-314 Import Reviewability + +The system shall provide import outputs and reports in a form that allows a user or client to inspect the relation between source context and imported result. + +--- + +## 7.4 Multi-File Document Handling + +### FR-401 Multi-File Source Declaration + +The system shall support projects consisting of multiple Markdown source files. + +### FR-402 Ordered Composition + +The system shall preserve declared source ordering when composing a multi-file document. + +### FR-403 Whole-Document Export + +The system shall support export of a multi-file project into a single reviewable document artifact. + +### FR-404 Source-Origin Awareness + +The system shall maintain source-origin information sufficient to support round-trip handling of multi-file documents. + +### FR-405 Source Redistribution + +The system shall support redistribution of imported content back into source-aligned outputs when source mapping information is available. + +### FR-406 Fallback Import Form + +When source redistribution cannot be completed safely, the system shall provide a valid merged Markdown result and indicate the fallback condition. + +### FR-407 Section Boundary Integrity Reporting + +The system shall report when imported edits cause ambiguity or breakage at tracked source or section boundaries. + +### FR-408 Partial Redistribution Reporting + +The system shall report when redistribution succeeds only for a subset of imported content. + +### FR-409 Redistribution Failure Reason Disclosure + +The system shall disclose why source redistribution could not be completed safely. + +### FR-410 Redistribution Outcome Classification + +The system shall classify redistribution outcomes as successful, partial, ambiguous, or failed. + +### FR-411 Source-Boundary Preservation Disclosure + +The system shall disclose whether tracked source boundaries were preserved, blurred, or broken during import and redistribution processing. + +### FR-412 Fallback Output Identification + +The system shall identify fallback merged outputs as fallback artifacts rather than ordinary source-aligned results. + +--- + +## 7.5 Feature Level Support + +## 7.5.1 LEVEL1 + +### FR-501 Heading Support + +The system shall export and import heading structures and preserve supported heading hierarchy. + +### FR-502 List Support + +The system shall export and import ordered and unordered lists and preserve list structure within supported cases. + +### FR-503 Table Support + +The system shall export and import supported table structures. + +### FR-504 Footnote Support + +The system shall export and import footnotes and preserve their association with referencing content. + +### FR-505 Image Support + +The system shall export and import supported images and preserve image references and associated descriptive metadata where available. + +### FR-506 Link Support + +The system shall export and import links and preserve supported link targets and visible text. + +### FR-507 LEVEL1 Processing Disclosure + +The system shall disclose when a document is processed under LEVEL1 expectations. + +### FR-508 LEVEL1 Unsupported Construct Visibility + +When constructs outside supported LEVEL1 scope are encountered in a LEVEL1 workflow, the system shall surface them explicitly rather than silently accepting them as preserved. + +## 7.5.2 LEVEL3 + +### FR-531 Cross-Reference Support + +The system shall support export and import workflows for supported cross references between labeled content elements. + +### FR-532 Numbered Figure Support + +The system shall support export of figures with captions and numbering and preserve figure identity sufficiently for supported round-trip usage. + +### FR-533 Automatic Diagram Support + +The system shall support diagrams derived from source declarations as part of document build/export workflows. + +### FR-534 Diagram Intent Preservation + +The system shall preserve the connection between diagram source intent and rendered output within the managed workflow. + +### FR-535 Bibliography Support + +The system shall support bibliography-aware document generation from structured citation inputs. + +### FR-536 Citation Preservation + +The system shall preserve supported citation semantics during round-trip processing or report when ambiguity prevents safe preservation. + +### FR-537 Feature-Level Compatibility Disclosure + +The system shall disclose whether a project, template family, or processing path supports LEVEL1 only or LEVEL3. + +### FR-538 LEVEL3 Processor Dependency Disclosure + +The system shall disclose when LEVEL3 processing depends on additional supporting processors or tools. + +### FR-539 LEVEL3 Partial Support Reporting + +The system shall report when a requested LEVEL3 workflow completes with only partial advanced feature support. + +### FR-540 Cross-Reference Resolution Reporting + +The system shall report whether supported cross references were resolved, preserved, degraded, or broken. + +### FR-541 Figure Identity Reporting + +The system shall report whether figure numbering and figure identity remained coherent within supported workflows. + +### FR-542 Bibliography Ambiguity Reporting + +The system shall report when bibliography or citation semantics cannot be safely preserved during import or comparison. + +--- + +## 7.6 Template and Style Management + +### FR-601 Built-In Family Availability + +The system shall provide three built-in document families named: + +* article +* book +* website + +### FR-602 Family Metadata Disclosure + +The system shall provide discoverable metadata for each available template/style family. + +### FR-603 Template Listing + +The system shall provide a way to list available template families. + +### FR-604 Style Listing + +The system shall provide a way to list available style families. + +### FR-605 Template Registration + +The system shall allow registration of an additional document template. + +### FR-606 Style Registration + +The system shall allow registration of an additional style definition. + +### FR-607 Paired Family Registration + +The system shall allow registration of an additional template/style family association. + +### FR-608 Registration Validation + +The system shall validate a proposed registration and report whether it is acceptable. + +### FR-609 Compatibility Declaration + +The system shall associate each template/style family with declared capability metadata, including applicable document types and feature-level support. + +### FR-610 Family Resolution + +The system shall resolve a family reference in a project to the corresponding registered template/style resources. + +### FR-611 Built-In Family Distinguishability + +The system shall distinguish built-in families from additionally registered families in listing and inspection outputs. + +### FR-612 Family Conflict Reporting + +The system shall report identifier conflicts or incompatible replacement attempts during registration. + +### FR-613 Family Capability Inspection + +The system shall provide a way to inspect the declared capabilities of a family independently of any particular project. + +### FR-614 Registration Outcome Reporting + +The system shall return a structured result for template, style, or family registration attempts, including success, warnings, and failure reasons. + +### FR-615 Family Selection Traceability + +The system shall allow a project output or report to identify which family definition was actually resolved and used. + +--- + +## 7.7 Validation and Drift Analysis + +### FR-701 Validation Invocation + +The system shall allow validation of a project without performing a full build or import. + +### FR-702 Validation Scope + +The system shall validate manifest integrity, referenced resources, selected feature level, and template/style compatibility. + +### FR-703 Build Preconditions Reporting + +The system shall report whether a project is functionally ready for build. + +### FR-704 Drift Comparison + +The system shall allow comparison of baseline and imported Markdown representations. + +### FR-705 Drift Classification + +The system shall classify detected differences into at least the following functional categories: + +* cosmetic +* normalized +* structural +* unsupported or ambiguous +* fatal + +### FR-706 Structural Drift Detection + +The system shall identify structural changes affecting supported document semantics. + +### FR-707 Cross-Reference Integrity Check + +The system shall detect and report broken or unresolved supported cross references. + +### FR-708 Figure Integrity Check + +The system shall detect and report supported figure numbering or identity inconsistencies. + +### FR-709 Bibliography Integrity Check + +The system shall detect and report unresolved bibliography or citation issues in supported workflows. + +### FR-710 Validation Result Output + +The system shall produce validation and drift results in a machine-consumable form and a human-consumable form. + +### FR-711 Validation Severity Disclosure + +The system shall distinguish blocking issues from warning-level issues in validation output. + +### FR-712 Comparison Input Disclosure + +The system shall identify which document states or artifacts were compared during drift analysis. + +### FR-713 Drift Summary Reporting + +The system shall provide a comparison summary in addition to detailed individual drift items. + +### FR-714 Drift Source Association + +Where source mapping is available, the system shall associate drift findings with relevant source files, sections, or tracked boundaries. + +### FR-715 Ambiguity Classification + +The system shall classify ambiguity findings distinctly from confirmed structural defects where the distinction is meaningful. + +### FR-716 Validation-Comparison Linkage + +The system shall support associating comparison outcomes with the validation and build/import states that produced them. + +--- + +## 7.8 CLI Functions + +### FR-801 Local CLI Availability + +The system shall provide a local command-line interface for core markidocx functions. + +### FR-802 CLI Build Command + +The CLI shall provide a command to build/export a project. + +### FR-803 CLI Import Command + +The CLI shall provide a command to import DOCX content into project-compatible Markdown outputs. + +### FR-804 CLI Validate Command + +The CLI shall provide a command to validate a project. + +### FR-805 CLI Diff Command + +The CLI shall provide a command to compare round-trip outputs or equivalent document states. + +### FR-806 CLI Inspect Command + +The CLI shall provide a command to inspect resolved project information. + +### FR-807 CLI Template Listing Command + +The CLI shall provide a command to list template families. + +### FR-808 CLI Style Listing Command + +The CLI shall provide a command to list styles or style families. + +### FR-809 CLI Registration Commands + +The CLI shall provide commands to register templates, styles, or families. + +### FR-810 CLI Test Command + +The CLI shall provide a command to execute the defined test suite or end-to-end validation workflow. + +### FR-811 CLI Exit Status Behavior + +The CLI shall return success, warning, or failure outcomes through distinguishable exit behavior and output. + +### FR-812 CLI Structured Output + +The CLI shall support a structured output mode for machine consumption. + +### FR-813 CLI Workflow Invocation + +The CLI shall provide a way to invoke supported composite workflows where such workflows are exposed by the system. + +### FR-814 CLI Evidence Retrieval + +The CLI shall provide a way to retrieve or emit available reports and evidence artifacts for relevant operations. + +### FR-815 CLI Capability Disclosure Command + +The CLI shall provide a command to retrieve system or project capability information. + +### FR-816 CLI Health and Version Commands + +The CLI shall provide a way to retrieve operational health and version information where applicable to the local or connected execution context. + +### FR-817 CLI Fallback Visibility + +The CLI shall visibly distinguish fallback and partial-result outputs from fully successful outputs. + +--- + +## 7.9 REST Service Functions + +### FR-901 REST Service Availability + +The system shall provide a REST-accessible service exposing core markidocx functions. + +### FR-902 REST Project Validation + +The service shall allow clients to submit a project for validation and receive a structured result. + +### FR-903 REST Build + +The service shall allow clients to request document build/export and retrieve resulting artifacts and reports. + +### FR-904 REST Import + +The service shall allow clients to submit DOCX content for import and receive generated Markdown-compatible outputs and reports. + +### FR-905 REST Drift Comparison + +The service shall allow clients to request drift analysis between supplied or project-associated document states. + +### FR-906 REST Template Listing + +The service shall provide an endpoint for listing available template families. + +### FR-907 REST Style Listing + +The service shall provide an endpoint for listing available styles or style families. + +### FR-908 REST Registration + +The service shall allow submission of additional template/style registrations and return validation results. + +### FR-909 REST Capability Inspection + +The service shall provide a way to retrieve supported capability and feature-level information. + +### FR-910 REST Health Disclosure + +The service shall provide a machine-readable health/status response. + +### FR-911 REST Version Disclosure + +The service shall provide a machine-readable version response. + +### FR-912 REST Structured Responses + +The service shall return structured responses that identify status, outputs, warnings, and errors. + +### FR-913 REST Workflow Invocation + +The service shall provide a way to invoke supported composite workflows through REST. + +### FR-914 REST Evidence Access + +The service shall provide access to reports and evidence artifacts produced by relevant operations. + +### FR-915 REST Operation Context Disclosure + +The service shall identify the project, family, feature level, and workflow context relevant to a response where applicable. + +### FR-916 REST Fallback and Partial Status Disclosure + +The service shall explicitly disclose fallback and partial-result conditions in structured responses. + +--- + +## 7.10 MCP Functions + +### FR-1001 MCP Availability + +The system shall provide an MCP-compatible interface exposing markidocx capabilities to agentic clients. + +### FR-1002 MCP Template Discovery + +The MCP interface shall expose a tool or equivalent operation to list available template families. + +### FR-1003 MCP Style Discovery + +The MCP interface shall expose a tool or equivalent operation to list available style families. + +### FR-1004 MCP Project Validation + +The MCP interface shall expose a tool or equivalent operation to validate a project. + +### FR-1005 MCP Project Inspection + +The MCP interface shall expose a tool or equivalent operation to inspect a project. + +### FR-1006 MCP Build + +The MCP interface shall expose a tool or equivalent operation to build/export a project. + +### FR-1007 MCP Import + +The MCP interface shall expose a tool or equivalent operation to import DOCX content. + +### FR-1008 MCP Drift Comparison + +The MCP interface shall expose a tool or equivalent operation to compare round-trip states. + +### FR-1009 MCP Test Execution + +The MCP interface shall expose a tool or equivalent operation to run end-to-end tests. + +### FR-1010 MCP Version Disclosure + +The MCP interface shall expose a tool or equivalent operation to disclose system version information. + +### FR-1011 MCP Resource Exposure + +The MCP interface shall expose relevant machine-consumable resources for manifests, capabilities, template metadata, style metadata, and current documentation corpus metadata. + +### FR-1012 MCP Workflow Invocation + +The MCP interface shall expose supported composite workflow functions to agentic clients. + +### FR-1013 MCP Evidence Retrieval + +The MCP interface shall expose a way to retrieve reports and evidence artifacts relevant to completed operations. + +### FR-1014 MCP Capability Context + +The MCP interface shall expose enough metadata for a client to determine whether a project, family, or workflow is compatible before invocation. + +### FR-1015 MCP Fallback Visibility + +The MCP interface shall explicitly surface fallback, ambiguity, degradation, and partial-result conditions in tool outputs or resources. + +--- + +## 7.11 Test and Regression Functions + +### FR-1101 Stable Documentation Corpus + +The system shall maintain the latest stable markidocx documentation as a managed documentation project. + +### FR-1102 Documentation-Based E2E Testing + +The system shall support execution of end-to-end validation using the latest stable markidocx documentation as the test corpus. + +### FR-1103 Round-Trip Regression Execution + +The system shall support a test flow in which the documentation corpus is built, exported, imported, and compared. + +### FR-1104 Template Coverage in E2E Testing + +The system shall support end-to-end testing against the built-in article, book, and website families where applicable. + +### FR-1105 Feature-Level Coverage in E2E Testing + +The system shall support execution of tests covering LEVEL1 and LEVEL3 behavior as represented in the stable documentation corpus. + +### FR-1106 Test Result Reporting + +The system shall provide a report identifying whether regression and end-to-end validation passed, warned, or failed. + +### FR-1107 Release Evidence Support + +The system shall support generation or assembly of evidence derived from end-to-end validation runs. + +### FR-1108 Regression Workflow Status Disclosure + +The system shall disclose which steps of a regression workflow completed, warned, failed, or fell back. + +### FR-1109 Documentation Corpus Identity Disclosure + +The system shall disclose which stable documentation corpus version or identity was used for a regression run. + +### FR-1110 Regression Artifact Traceability + +The system shall allow regression outputs, reports, and evidence to be associated with the corresponding test run. + +--- + +## 7.12 Error and Warning Behavior + +### FR-1201 Explicit Failure Reporting + +The system shall explicitly report functional failures rather than silently omitting failed operations. + +### FR-1202 Explicit Warning Reporting + +The system shall explicitly report warnings when an operation completes with ambiguity, normalization, unsupported constructs, or partial degradation. + +### FR-1203 Unsupported Construct Visibility + +The system shall surface unsupported or ambiguous constructs in import, export, validation, or diff results. + +### FR-1204 Partial Result Disclosure + +When an operation produces partial results, the system shall indicate the partial nature of those results. + +### FR-1205 Non-Silent Degradation + +The system shall not silently discard known document constructs that fall outside supported round-trip behavior. + +### FR-1206 Ambiguity Reporting + +The system shall explicitly distinguish ambiguous outcomes from confirmed successful preservation when the distinction is meaningful. + +### FR-1207 Fallback Reporting + +The system shall explicitly report when a workflow falls back from its preferred processing path to a degraded but usable path. + +### FR-1208 Severity Visibility + +The system shall make severity or functional significance visible in warnings and failures. + +### FR-1209 Reason Disclosure + +The system shall provide a reason or classification for failures, warnings, fallback states, and ambiguities. + +### FR-1210 Output State Identification + +The system shall identify whether a returned output is final, partial, fallback, degraded, or unresolved. + +--- + +## 7.13 Composite Workflow Functions + +### FR-1301 Single-File Round-Trip Workflow + +The system shall support a composite workflow that validates, builds, imports, and compares a single-file project. + +### FR-1302 Multi-File Round-Trip Workflow + +The system shall support a composite workflow that inspects, validates, builds, imports, redistributes or falls back, and compares a multi-file project. + +### FR-1303 Composite Workflow Result Reporting + +The system shall return a structured result for a composite workflow that includes the statuses and outputs of its constituent steps. + +### FR-1304 Composite Workflow Step Visibility + +The system shall disclose which constituent steps were executed in a composite workflow. + +### FR-1305 Composite Workflow Fallback Visibility + +The system shall disclose whether a composite workflow completed fully, completed with fallback, completed partially, or failed. + +### FR-1306 Release Regression Workflow + +The system shall support a composite workflow that performs end-to-end regression on the latest stable documentation corpus. + +### FR-1307 Family-Switch Build Workflow + +The system shall support a workflow in which the same project is built under more than one compatible family and the results are separately reported. + +### FR-1308 Workflow Reusability Across Interfaces + +Where a composite workflow is supported, the system shall expose it consistently through the relevant supported interfaces. + +### FR-1309 Workflow Context Identity + +The system shall provide identity information for a composite workflow execution sufficient to associate its outputs and evidence. + +### FR-1310 Workflow Output Aggregation + +The system shall aggregate build, import, validation, comparison, and related outputs into a coherent workflow result where those operations are part of the invoked workflow. + +--- + +## 7.14 Evidence and Report Management + +### FR-1401 Validation Report Availability + +The system shall make validation results available as reusable reports. + +### FR-1402 Build Report Availability + +The system shall make build results available as reusable reports. + +### FR-1403 Import Report Availability + +The system shall make import results available as reusable reports. + +### FR-1404 Drift Report Availability + +The system shall make comparison and drift results available as reusable reports. + +### FR-1405 Warning and Ambiguity Report Availability + +The system shall make warnings, ambiguities, degradations, and fallback conditions reviewable as structured report content. + +### FR-1406 Release Evidence Assembly + +The system shall support assembly of a coherent release evidence set from relevant validation, build, import, comparison, and regression outputs. + +### FR-1407 Evidence Composition Disclosure + +The system shall identify which reports, artifacts, and operation results are included in an evidence set. + +### FR-1408 Evidence Status Summary + +The system shall provide a summary of success, warnings, fallback conditions, partial results, and failures across an evidence set. + +### FR-1409 Evidence Retrieval Across Interfaces + +The system shall allow reports and evidence artifacts to be retrieved through supported interfaces where those interfaces expose the originating operations. + +### FR-1410 Evidence Traceability + +The system shall support associating reports and evidence with the project, family, feature level, workflow, and run context that produced them. + +### FR-1411 Report Human Readability + +The system shall provide report output in a form suitable for human inspection. + +### FR-1412 Report Machine Readability + +The system shall provide report output in a machine-consumable form. + +### FR-1413 Report Completeness Disclosure + +The system shall disclose when a report or evidence set is incomplete. + +### FR-1414 Release Decision Support Visibility + +The system shall make it possible to determine from evidence outputs whether a release-time workflow completed cleanly, completed with warnings, or failed. + +--- + +# 8. Functional Use Cases + +## UC-01 Single-File Round-Trip + +A user provides a single Markdown project, builds DOCX, edits the DOCX, imports it back, and receives an updated Markdown result plus drift report. + +## UC-02 Multi-File Review Workflow + +A user provides a multi-file project, exports one DOCX for review, imports the reviewed DOCX, and receives redistributed or merged Markdown outputs with section mapping status. + +## UC-03 Template Switching + +A user builds the same content using article, book, and website families and receives corresponding output artifacts without changing the source content. + +## UC-04 Validation Before Build + +A user validates a project and receives confirmation of readiness or a list of blocking issues. + +## UC-05 External Automation + +An external system submits a project to the REST service for build, import, or comparison and receives structured results. + +## UC-06 Agentic Interaction + +An MCP client discovers available templates, validates a project, triggers a build, and retrieves validation outcomes. + +## UC-07 Product Self-Test + +A release process runs end-to-end tests against the latest stable markidocx documentation and records regression status. + +## UC-08 Warning and Ambiguity Review + +A user inspects warnings, degradations, ambiguities, fallback conditions, and related report details before deciding whether and how to apply results. + +## UC-09 Release Evidence Review + +A release manager or equivalent actor reviews assembled validation, build, import, and comparison evidence for a release decision. + +## UC-10 Composite Workflow Invocation + +A user or client invokes a full round-trip or regression workflow as one meaningful system operation and receives a combined result. + +--- + +# 9. Functional Constraints + +### FC-01 Supported Semantic Envelope + +The system shall only claim preservation for constructs within the declared supported feature levels and managed workflow boundaries. + +### FC-02 Project-Scoped Operation + +Build, import, validation, and drift functions shall operate in relation to an explicit project context or explicitly supplied artifact set. + +### FC-03 Family-Scoped Capability + +Template/style application shall be constrained by the declared capabilities of the selected family. + +### FC-04 Fallback Disclosure + +Whenever the system falls back from source-aligned redistribution to merged or degraded output, it shall disclose that fallback. + +### FC-05 Composite Workflow Transparency + +Composite workflows shall not obscure the outcomes of their constituent functional steps. + +### FC-06 Evidence Traceability + +Evidence and reports shall remain attributable to their originating operation or workflow context. + +--- + +# 10. Acceptance-Oriented Functional Summary + +markidocx shall be considered functionally conformant to this FRS when it can, at minimum: + +1. accept and validate a project manifest +2. compose single-file and multi-file Markdown documents +3. export DOCX using built-in document families +4. import edited DOCX back into Markdown-compatible outputs +5. support all declared LEVEL1 functions +6. support declared LEVEL3 functions for managed cases +7. detect and classify round-trip drift +8. expose core functions through CLI +9. expose core functions through REST +10. expose core functions through MCP +11. register additional templates and styles +12. run end-to-end tests using the latest stable markidocx documentation corpus +13. expose fallback, ambiguity, and partial-result states explicitly +14. support composite workflow invocation for meaningful round-trip scenarios +15. produce reusable reports and release evidence artifacts + +--- + +# 11. Related Artifacts + +This FRS is expected to relate to: + +* PRD: markidocx +* UCC: markidocx +* Non-Functional Requirements document +* API/interface contracts +* schema definitions for manifests and registrations +* test specifications +* acceptance criteria catalog +* system design specification +* architecture decision records + +--- + +# 12. Appendix: Suggested Requirement Trace Anchors + +A minimal traceability map should connect: + +* PRD product goals → FRS requirement groups +* UCC use cases → FRS requirement IDs +* FRS requirement IDs → interface contracts +* FRS requirement IDs → acceptance tests +* FRS requirement Iression scenarios + +Example trace anchors: + +* PRD Round-Trip Editing → FR-201 to FR-308, FR-1301 to FR-1305 +* PRD Multi-File Composition → FR-401 to FR-412, FR-1302 +* PRD Built-In Families → FR-601 to FR-615 +* PRD CLI/REST/MCP accessibility → FR-801 to FR-1015 +* PRD E2E documentation corpus → FR-1101 to FR-1110 +* UCC Warning and ambiguity review → FR-1202 to FR-1210, FR-1405 +* UCC Release evidence review → FR-1406 to FR-1414 +* UCC Composite workflow invocation → FR-1301 to FR-1310 + +--- + +# 13. Appendix: UCC to FRS Traceability Matrix + +## Project and Manifest + +* UC-001 Define document project ↔ FR-101 to FR-110 +* UC-002 Inspect project configuration ↔ FR-104 to FR-110 +* UC-003 Validate project readiness ↔ FR-701 to FR-703, FR-711 + +## Build and Export + +* UC-004 Build DOCX review artifact ↔ FR-201 to FR-214 +* UC-005 Build using alternate family ↔ FR-204 to FR-205, FR-210 to FR-212, FR-603 to FR-615 + +## Import and Round-Trip + +* UC-006 Import edited DOCX into Markdown ↔ FR-301 to FR-314 +*d-trip single-file document ↔ FR-201 to FR-308, FR-704 to FR-716, FR-1301 to FR-1305 +* UC-008 Round-trip multi-file document ↔ FR-401 to FR-412, FR-704 to FR-716, FR-1302 to FR-1305 +* UC-009 Redistribute imported edits to source files ↔ FR-404 to FR-412 +* UC-010 Fallback to merged Markdown import ↔ FR-406, FR-412, FR-1207, FR-1210 +* UC-011 Detect round-trip drift ↔ FR-704 to FR-716 +* UC-022 Review warning and ambiguity report ↔ FR-1202 to FR-1210, FR-1405, FR-1411 to FR-1412 + +## Feature Levels + +ld LEVEL1 document ↔ FR-501 to FR-508 +* UC-015 Build LEVEL3 document ↔ FR-531 to FR-542 +* UC-016 Generate automatic diagrams ↔ FR-533 to FR-534, FR-538 +* UC-017 Process bibliography-aware document ↔ FR-535 to FR-536, FR-542 + +## Interfaces + +* UC-018 Execute local CLI workflow ↔ FR-801 to FR-817 +* UC-019 Execute REST-based workflow ↔ FR-901 to FR-916 +* UC-020 Execute MCP-based workflow ↔ FR-1001 to FR-1015 +* UC-023 Retrieve system capability metadata ↔ FR-105, FR-537, FR-613, FR-815, FR-909, FR-1011, FR-1014 +* UC-024 Retrieve health and version status ↔ FR-816, FR-910 to FR-911, FR-1010 + +## Release and Testing + +* UC-021 Run end-to-end regression on stable docs ↔ FR-1101 to FR-1110, FR-1306 +* UC-025 Build and inspect release evidence ↔ FR-1107 to FR-1110, FR-1401 to FR-1414 + +--- + +# 14. Concise Revision Summary + +This revision preserves the prior FRS and extends it in four main ways: + +* it adds **composite workflow requirements** +* it adds **evidence and report management requirements** +* it thens **fallback, ambiguity, and partial-result handling** +* it improves **traceability to the UCC** + +That makes the FRS better aligned with the richer actor-goal structure without changing the original product intent. + diff --git a/specs/MarkiDocxProductRequirementsDocument_v0.1.md b/specs/MarkiDocxProductRequirementsDocument_v0.1.md new file mode 100644 index 0000000..4b321f3 --- /dev/null +++ b/specs/MarkiDocxProductRequirementsDocument_v0.1.md @@ -0,0 +1,391 @@ +Below is a **PRD for the markidocx product**, structured according to your **InfoTechPrimer PRD model** and respecting the principle of **implementation independence** (no CLI flags, API routes, or architecture details). +Implementation specifics such as CLI/REST/MCP interfaces belong in the **FRS**, which would normally follow this PRD. + +--- + +# PRD + +*Product Requirement Document* + +# Product Requirements Document: markidocx + +## 1. Definition + +**markidocx** is a product that enables **reliable round-trip editing between Markdown and Microsoft Word documents** while preserving document structure and semantic intent. + +The product addresses a recurring coordination problem in technical documentation and knowledge workflows: +Markdown is widely used for structured authoring and version-controlled collaboration, while Word remains the dominant format for editorial review, stakeholder collaboration, and formal document exchange. + +markidocx provides a controlled workflow in which: + +* Markdown remains the **canonical structured source** +* Word serves as a **managed editorial interface** +* repeated conversion cycles preserve semantic structure +* template-driven styling separates presentation from content +* large multi-file documents remain manageable across the editing lifecycle + +The product is intended for organizations that require **structured documentation workflows with Word-based collaboration**, including engineering teams, documentation teams, standards bodies, and regulated environments. + +--- + +## 2. Context + +markidocx operates at the intersection of: + +* **technical documentation systems** +* **collaborative editorial workflows** +* **requirements and specification authoring** +* **knowledge management infrastructures** + +In many modern documentation environments: + +* engineers and technical authors write in **Markdown** +* documents are stored in **version-controlled repositories** +* external stakeholders and reviewers operate primarily in **Word** + +This mismatch creates friction: + +* Word-based edits often break structured content +* Markdown workflows are inaccessible to non-technical reviewers +* conversion pipelines introduce structural drift + +markidocx exists to bridge these environments by establishing a **controlled round-trip workflow** where: + +* Markdown remains structurally authoritative +* Word editing is supported within a defined semantic envelope +* conversion processes are deterministic and inspectable + +The product acts as a **boundary system between structured authoring and editorial collaboration**. + +--- + +## 3. Core Concepts + +### Round-Trip Editing + +Round-trip editing is the ability to export a document into another format for editing and later re-import the modified document while preserving structural meaning. + +markidocx establishes a disciplined round-trip process between Markdown and Word. + +--- + +### Canonical Source Model + +The canonical source of truth is **Markdown structured documents**. + +Word documents generated by the system are considered **editorial projections** of the canonical source rather than independent authoritative artifacts. + +--- + +### Semantic Preservation + +The product guarantees preservation of document semantics across editing cycles within defined feature levels. + +Preserved semantics include structural constructs such as headings, lists, references, and citations. + +--- + +### Template-Driven Presentation + +Document presentation is controlled by **document templates and style definitions**. + +This allows the same content to be exported in different presentation forms without modifying the source. + +Built-in document families include: + +* article +* book +* website + +--- + +### Multi-File Document Composition + +Large documents are often structured across multiple files for maintainability. + +markidocx supports multi-file composition and ensures that editing cycles do not collapse this structure unnecessarily. + +--- + +### Feature Levels + +markidocx distinguishes between two functional feature tiers: + +**LEVEL1 – Core Document Structure** + +* headings +* lists +* tables +* footnotes +* images +* links + +**LEVEL3 – Advanced Scholarly / Technical Features** + +* cross references +* numbered figures +* automatic diagrams +* bibliography + +Feature levels define the guarantees the system provides during round-trip editing. + +--- + +### Drift Detection + +Structural drift may occur when editing documents in Word. + +markidocx introduces mechanisms to detect and report semantic differences between: + +* original Markdown sources +* re-imported Markdown versions + +This allows users to understand and manage structural changes. + +--- + +## 4. Scope and Non-Scope + +### In Scope + +The product must support: + +* Markdown ↔ Word round-trip editing +* multi-file document composition +* template-based document styling +* two defined feature levels (LEVEL1 and LEVEL3) +* preservation of document structure across editing cycles +* detection and reporting of semantic drift +* support for editorial collaboration workflows +* extensibility through additional document templates and styles +* automated testing of round-trip behavior using product documentation + +The product must provide interfaces that enable: + +* local document workflows +* automated integration into documentation pipelines +* programmatic interaction through service interfaces + +--- + +### Out of Scope + +The product does not attempt to: + +* replace word processors +* provide a graphical document editor +* support arbitrary Word document constructs +* act as a full document layout system +* enforce a specific documentation methodology +* replace existing publishing systems + +markidocx focuses specifically on **structured round-trip workflows**, not full document production ecosystems. + +--- + +## 5. Practical Implications + +Adopting markidocx introduces a structured approach to document collaboration. + +Benefits include: + +* improved collaboration between technical and non-technical stakeholders +* preservation of structured documentation in version-controlled environments +* reduced manual cleanup after Word-based reviews +* deterministic document generation workflows +* improved traceability between authored content and reviewed documents + +Trade-offs include: + +* the need to operate within supported feature boundaries +* the requirement to use defined templates and styles +* occasional limitations when importing highly customized Word content + +The system is particularly valuable for organizations that: + +* maintain long-lived technical documentation +* operate cross-disciplinary teams +* require traceable document evolution +* manage complex specifications or manuals + +--- + +## 6. Product Use Cases + +The product must support the following key use cases. + +### Technical Review Workflow + +A document written in Markdown is exported to Word for review by stakeholders and later re-imported with edits incorporated into the Markdown source. + +--- + +### Multi-Chapter Document Editing + +A large multi-file document is exported as a single Word document for external review and later re-imported without collapsing the source structure. + +--- + +### Specification Publishing + +A technical specification written in Markdown is exported using a formal template suitable for distribution and archival. + +--- + +### Documentation Collaboration + +Technical authors maintain Markdown sources while subject matter experts provide editorial feedback using Word. + +--- + +### Knowledge System Integration + +The product integrates with documentation pipelines, knowledge repositories, or automated publication workflows. + +--- + +### Regression Testing of Documentation + +The product documentation itself serves as a round-trip editing test corpus, validating product functionality across releases. + +--- + +## 7. Constraints and Assumptions + +### Constraints + +* Word document editing environments vary widely. +* Markdown dialects differ across ecosystems. +* Some Word features cannot be reliably mapped to Markdown. +* Diagram and bibliography rendering depend on external tools. + +The product must therefore operate within defined semantic boundaries. + +--- + +### Assumptions + +* Markdown remains the authoritative authoring format. +* Word is used primarily for editing and review rather than canonical storage. +* document structure is maintained using supported constructs. +* editorial users operate within template-defined formatting environments. + +--- + +## 8. Success Criteria + +markidocx is considered successful when it achieves the following outcomes. + +### Structural Stability + +Repeated Markdown → Word → Markdown cycles preserve document structure within supported feature levels. + +--- + +### Editorial Accessibility + +Non-technical stakeholders can review and edit documents without interacting directly with Markdown sources. + +--- + +### Template Flexibility + +Organizations can apply different document presentation styles without altering content. + +--- + +### Multi-Document Scalability + +Large documents composed from multiple files remain manageable across editing cycles. + +--- + +### Detectable Drift + +Structural changes introduced during editing are visible and analyzable. + +--- + +### Pipeline Compatibility + +The product integrates into automated documentation and publishing pipelines. + +--- + +### Testable Documentation + +The product documentation itself can be used as a stable end-to-end validation corpus. + +--- + +## 9. Dependencies + +The product depends on: + +* document conversion technologies capable of translating between Markdown and Word formats +* diagram rendering tools for automated diagrams +* citation and bibliography processing tools +* structured document templates +* consistent Markdown dialect support + +External dependencies must be manageable without introducing excessive operational complexity. + +--- + +## 10. Risks + +### Semantic Drift Risk + +Editing in Word may unintentionally alter document structure. + +--- + +### Template Misuse + +Users may modify templates in ways that break round-trip guarantees. + +--- + +### Over-complex Feature Expectations + +Users may expect support for all Word features, which is not feasible. + +--- + +### Workflow Discipline + +Successful operation depends on maintaining structured authoring practices. + +--- + +## 11. Related Concepts + +* Markdown Documentation Systems +* Structured Authoring +* Technical Writing Pipelines +* Documentation-as-Code +* Word Editorial Workflows +* Publishing Toolchains +* Knowledge Repositories + +Adjacent artifacts include: + +* Functional Requirements Specification (FRS) +* Architecture Documentation +* Technical Specifications +* Template and Style Definitions +* Round-Trip Validation Reports + +--- + +## 12. Appendix: Product Positioning + +markidocx belongs to a class of tools that bridge structured authoring and editorial collaboration. + +Compared with typical Markdown toolchains, the product focuses specifically on **controlled editorial round-trip workflows** rather than pure publishing. + +Compared with office-based authoring systems, the product preserves **version-controlled structured sources**. + +Its value lies in enabling **structured documentation ecosystems that remain compatible with Word-centric collaboration environments**. + +xxx diff --git a/specs/MarkiDocxUseCaseCatalog_v0.1.md b/specs/MarkiDocxUseCaseCatalog_v0.1.md new file mode 100644 index 0000000..5b9732d --- /dev/null +++ b/specs/MarkiDocxUseCaseCatalog_v0.1.md @@ -0,0 +1,1412 @@ +# UCC + +*Use Case Catalog* + +# Use Case Catalog: markidocx + +**System Scope:** markidocx +**Artifact Type:** Use Case Catalog +**Purpose:** Structured catalog of actor-goal-centered use cases for the markidocx round-trip editing system +**Status:** Draft +**Version:** 1.0 +**Parent Artifacts:** PRD markidocx, FRS markidocx + +--- + +# 1. Definition + +This Use Case Catalog defines the externally observable functional behavior of **markidocx** from the perspective of its actors. + +markidocx enables controlled **Markdown ↔ DOCX round-trip editing** with support for: + +* local CLI usage +* REST-based service interaction +* MCP-based agent interaction +* template/style-driven document generation +* multi-file composition +* feature-level processing +* validation and drift detection +* end-to-end regression based on the latest stable markidocx documentation corpus + +This catalog organizes the major actor goals that the system must support and provides structured use case descriptions suitable for traceability into the FRS and acceptance artifacts. + +--- + +# 2. Context + +markidocx sits between structured Markdown authoring and Word-centric editorial collaboration. + +Its main functional challenge is not simple format conversion, but **managed round-trip behavior** under defined semantic constraints. + +The catalog therefore focuses on use cases where actors need to: + +* define a document project +* inspect and validate project readiness +* build review artifacts +* import edited DOCX files back into Markdown +* preserve or recover structure in multi-file projects +* apply template/style families +* detect drift +* automate workflows through service interfaces +* access the system through agentic tooling + +This UCC is positioned between product goals and detailed functional requirements. + +--- + +# 3. Actor Model + +## 3.1 Primary Actors + +### A-01 Document Author + +A person maintaining canonical Markdown sources and preparing documents for export, review, and re-import. + +### A-02 Technical Editor + +A person responsible for document quality, structure, and consistency across editing cycles. + +### A-03 Reviewer + +A stakeholder who edits or comments on generated DOCX artifacts, usually without direct interaction with Markdown sources. + +### A-04 Build Operator + +A person or automation operator invoking builds, validations, or regression flows locally or in controlled environments. + +### A-05 Integration Client + +An external system calling the REST interface to validate, build, import, compare, or register artifacts. + +### A-06 MCP Client + +An agentic tool using the MCP interface to inspect projects, trigger operations, and retrieve results. + +### A-07 Template Administrator + +A person responsible for registering, updating, or governing templates and styles. + +### A-08 Release Manager + +A person or automation responsible for release validation using the stable documentation corpus as end-to-end testcase. + +--- + +## 3.2 Supporting Actors + +### SA-01 Template Registry + +Logical externalized registry of available built-in and registered template/style families. + +### SA-02 Diagram Renderer + +A rendering toolchain used for automatic diagrams in LEVEL3 workflows. + +### SA-03 Bibliography Processor + +A citation/bibliography-capable processor used in bibliography-aware workflows. + +### SA-04 File System / Artifact Store + +A storage context for source bundles, generated artifacts, imports, and reports. + +### SA-05 Source Mapping Context + +A project-specific mapping context allowing re-association of imported content to original source boundaries. + +--- + +# 4. Use Case Levels + +The catalog uses three abstraction levels: + +* **Summary** – broad actor goals spanning multiple interactions +* **User-goal** – complete actor goals that produce meaningful results +* **Subfunction** – reusable lower-level interactions supporting user goals + +The primary catalog emphasis is on **user-goal** use cases. + +--- + +# 5. Catalog Index + +| ID | Name | Level | Primary Actor | Goal | +| ------ | ------------------------------------------- | ----------: | ---------------------- | ---------------------------------------------------------------------- | +| UC-001 | Define document project | User-goal | Document Author | Declare a document project usable by markidocx | +| UC-002 | Inspect project configuration | User-goal | Document Author | Understand the resolved structure and capabilities of a project | +| UC-003 | Validate project readiness | User-goal | Build Operator | Determine whether a project is functionally ready | +| UC-004 | Build DOCX review artifact | User-goal | Document Author | Produce a DOCX artifact from Markdown sources | +| UC-005 | Build using alternate family | User-goal | Technical Editor | Export the same source using article, book, or website family | +| UC-006 | Import edited DOCX into Markdown | User-goal | Document Author | Re-import reviewed DOCX content into Markdown-compatible form | +| UC-007 | Round-trip single-file document | Summary | Document Author | Complete a full single-file Markdown → DOCX → Markdown cycle | +| UC-008 | Round-trip multi-file document | Summary | Technical Editor | Complete a full multi-file round-trip cycle with source-aware handling | +| UC-009 | Redistribute imported edits to source files | User-goal | Technical Editor | Re-associate imported content with original source files | +| UC-010 | Fallback to merged Markdown import | User-goal | Technical Editor | Recover usable Markdown when source redistribution is ambiguous | +| UC-011 | Detect round-trip drift | User-goal | Technical Editor | Compare baseline and imported content for semantic drift | +| UC-012 | List available families | User-goal | Template Administrator | Discover built-in and registered template/style families | +| UC-013 | Register additional template family | User-goal | Template Administrator | Add a new template/style family to the system | +| UC-014 | Build LEVEL1 document | User-goal | Document Author | Produce and round-trip a document using LEVEL1 features | +| UC-015 | Build LEVEL3 document | User-goal | Technical Editor | Produce and round-trip a document using LEVEL3 features | +| UC-016 | Generate automatic diagrams | Subfunction | Document Author | Include rendered diagrams derived from source declarations | +| UC-017 | Process bibliography-aware document | Subfunction | Technical Editor | Include citations and bibliography during build/import workflows | +| UC-018 | Execute local CLI workflow | Summary | Build Operator | Perform markidocx operations through the CLI | +| UC-019 | Execute REST-based workflow | Summary | Integration Client | Perform markidocx operations through the REST service | +| UC-020 | Execute MCP-based workflow | Summary | MCP Client | Perform markidocx operations through MCP tools | +| UC-021 | Run end-to-end regression on stable docs | User-goal | Release Manager | Validate latest stable markidocx documentation as canonical testcase | +| UC-022 | Review warning and ambiguity report | User-goal | Technical Editor | Inspect unsupported, degraded, or ambiguous outcomes | +| UC-023 | Retrieve system capability metadata | User-goal | Integration Client | Discover supported feature levels and interfaces | +| UC-024 | Retrieve health and version status | User-goal | Build Operator | Determine operational availability and version state | +| UC-025 | Build and inspect release evidence | User-goal | Release Manager | Produce auditable build/import/diff evidence for a release | + +--- + +# 6. Cross-Reference Map + +* **UC-007 Round-trip single-file document** includes UC-003, UC-004, UC-006, UC-011 +* **UC-008 Round-trip multi-file document** includes UC-002, UC-003, UC-004, UC-006, UC-009 or UC-010, UC-011 +* **UC-015 Build LEVEL3 document** includes UC-016 and UC-017 where applicable +* **UC-018 Execute local CLI workflow** varies UC-003, UC-004, UC-006, UC-011, UC-012, UC-013, UC-021 +* **UC-019 Execute REST-based workflow** varies UC-003, UC-004, UC-006, UC-011, UC-023, UC-024 +* **UC-020 Execute MCP-based workflow** varies UC-002, UC-003, UC-004, UC-006, UC-011, UC-023 + +--- + +# 7. Detailed Use Cases + +--- + +## UC-001 Define document project + +**Level:** User-goal +**Primary Actor:** Document Author +**Supporting Actors:** File System / Artifact Store +**Goal:** Create a valid project definition that markidocx can process + +### Preconditions + +* The actor has a set of Markdown sources or intends to create one +* The actor knows the intended document type and feature level +* Required source files are accessible + +### Guarantees + +**Success** + +* A project definition exists +* The project declares source files, feature level, and selected family references +* The project can be submitted for inspection or validation + +**Minimal** + +* No existing project data is modified unintentionally + +### Main Success Scenario + +1. The actor provides a project definition for a document set. +2. The system reads the provided manifest content. +3. The system recognizes declared sources, feature level, and family references. +4. The system acknowledges the project as a recognizable markidocx project. +5. The actor can proceed with inspection or validation. + +### Extensions + +* **3a.** A referenced source is missing. + The system reports the missing resource. +* **3b.** The manifest contains unsupported settings. + The system reports invalid or unsupported configuration. +* **4a.** Template or style references cannot be resolved. + The system reports unresolved family references. + +### Special Requirements + +* The use case must remain independent of interface channel +* The project definition must be reusable across CLI, REST, and MCP workflows + +--- + +## UC-002 Inspect project configuration + +**Level:** User-goal +**Primary Actor:** Document Author +**Goal:** View the resolved structure and effective capabilities of a project + +### Preconditions + +* A recognizable project definition exists + +### Guarantees + +**Success** + +* The actor receives a resolved view of project structure +* The actor can see source ordering, family selection, and effective feature level + +**Minimal** + +* The project remains unchanged + +### Main Success Scenario + +1. The actor requests inspection of a project. +2. The system resolves the project definition. +3. The system determines the effective source ordering. +4. The system determines selected family and declared capability level. +5. The system returns inspection output to the actor. + +### Extensions + +* **2a.** The project cannot be resolved. + The system reports why inspection cannot proceed. +* **4a.** Registered family metadata is incomplete. + The system reports incomplete capability resolution. + +### Related Use Cases + +* UC-003 Validate project readiness +* UC-008 Round-trip multi-file document + +--- + +## UC-003 Validate project readiness + +**Level:** User-goal +**Primary Actor:** Build Operator +**Goal:** Determine whether a project is functionally ready for processing + +### Preconditions + +* A project definition exists + +### Guarantees + +**Success** + +* The actor receives a validation result +* Blocking and non-blocking issues are distinguished +* Functional readiness is made explicit + +**Minimal** + +* The project remains unchanged + +### Main Success Scenario + +1. The actor submits a project for validation. +2. The system checks manifest consistency. +3. The system checks referenced resources. +4. The system checks feature-level and family compatibility. +5. The system determines readiness status. +6. The system returns validation output. + +### Extensions + +* **2a.** The manifest is malformed. + The system reports validation failure. +* **3a.** A required resource is unavailable. + The system reports a blocking issue. +* **4a.** The selected family does not support the declared feature level. + The system returns a compatibility failure. +* **5a.** Non-blocking issues exist. + The system returns a warning state rather than outright failure. + +### Related Use Cases + +* UC-004 Build DOCX review artifact +* UC-021 Run end-to-end regression on stable docs + +--- + +## UC-004 Build DOCX review artifact + +**Level:** User-goal +**Primary Actor:** Document Author +**Supporting Actors:** Template Registry, File System / Artifact Store +**Goal:** Generate a DOCX artifact from the project’s Markdown sources + +### Preconditions + +* The project is valid or sufficiently processable +* The selected template family is available + +### Guarantees + +**Success** + +* A DOCX artifact is generated +* Declared project content is included according to supported features +* Build status and artifact metadata are returned + +**Minimal** + +* No existing canonical Markdown source is altered + +### Main Success Scenario + +1. The actor requests a DOCX build for a project. +2. The system resolves the project structure. +3. The system composes the Markdown sources. +4. The system resolves the selected template/style family. +5. The system applies supported processing for the declared feature level. +6. The system generates a DOCX artifact. +7. The system returns the artifact reference and build report. + +### Extensions + +* **2a.** The project cannot be resolved. + The system reports a build failure. +* **4a.** The selected family is unavailable. + The system reports an unresolved family reference. +* **5a.** A supported asset cannot be resolved. + The system returns a warning or failure depending on severity. +* **6a.** Build output is generated with degradations. + The system returns the artifact with warnings. + +### Related Use Cases + +* UC-005 Build using alternate family +* UC-014 Build LEVEL1 document +* UC-015 Build LEVEL3 document + +--- + +## UC-005 Build using alternate family + +**Level:** User-goal +**Primary Actor:** Technical Editor +**Goal:** Build the same source content using a different built-in or registered family + +### Preconditions + +* A project definition exists +* More than one compatible family is available or known + +### Guarantees + +**Success** + +* The actor receives an output artifact built using the selected alternate family +* Canonical content remains unchanged + +**Minimal** + +* No incompatible family is silently applied + +### Main Success Scenario + +1. The actor chooses an alternate family for the build. +2. The system resolves the requested family. +3. The system checks capability compatibility. +4. The system builds the document using the selected family. +5. The system returns the resulting artifact and build report. + +### Extensions + +* **2a.** The requested family is unknown. + The system reports the family cannot be resolved. +* **3a.** The requested family is incompatible with the project’s feature level. + The system returns a compatibility failure. + +### Related Use Cases + +* UC-012 List available families +* UC-013 Register additional template family + +--- + +## UC-006 Import edited DOCX into Markdown + +**Level:** User-goal +**Primary Actor:** Document Author +**Supporting Actors:** Source Mapping Context, File System / Artifact Store +**Goal:** Import an edited DOCX into Markdown-compatible output + +### Preconditions + +* A DOCX document exists for import +* If source-aware import is expected, a project context exists + +### Guarantees + +**Success** + +* The system produces Markdown-compatible import output +* Supported structure is preserved +* Import warnings and ambiguities are disclosed + +**Minimal** + +* Existing source content remains unchanged unless the actor deliberately applies imported output later + +### Main Success Scenario + +1. The actor submits a DOCX file for import. +2. The system recognizes the import request context. +3. The system extracts supported document content. +4. The system maps recognized content into Markdown-compatible representation. +5. The system applies project-aware or source-aware mapping when available. +6. The system produces import output and reports. +7. The actor receives the output and related warnings or mapping status. + +### Extensions + +* **2a.** No project context is provided. + The system produces a valid import result without project-aware redistribution. +* **3a.** The DOCX contains unsupported constructs. + The system reports unsupported constructs explicitly. +* **5a.** Source mapping is ambiguous. + The system reports ambiguity and may fall back to merged output. +* **6a.** Import completes with degradations. + The system returns output plus warning classification. + +### Related Use Cases + +* UC-009 Redistribute imported edits to source files +* UC-010 Fallback to merged Markdown import +* UC-022 Review warning and ambiguity report + +--- + +## UC-007 Round-trip single-file document + +**Level:** Summary +**Primary Actor:** Document Author +**Goal:** Complete a full single-file round-trip editing cycle + +### Preconditions + +* A valid single-file project exists + +### Guarantees + +**Success** + +* A DOCX review artifact is built +* The edited DOCX is imported back +* Semantic drift is reported + +**Minimal** + +* Canonical source remains recoverable + +### Main Success Scenario + +1. The actor validates the single-file project. +2. The actor builds a DOCX artifact. +3. A reviewer edits the DOCX. +4. The actor imports the edited DOCX. +5. The actor compares baseline and imported Markdown. +6. The system returns a drift report. +7. The actor decides how to apply imported changes. + +### Includes + +* UC-003 Validate project readiness +* UC-004 Build DOCX review artifact +* UC-006 Import edited DOCX into Markdown +* UC-011 Detect round-trip drift + +### Extensions + +* **4a.** Import contains unsupported constructs. + The system provides import output with explicit warnings. +* **5a.** Structural drift is detected. + The system highlights drift classification. + +--- + +## UC-008 Round-trip multi-file document + +**Level:** Summary +**Primary Actor:** Technical Editor +**Goal:** Complete a round-trip cycle for a multi-file project while preserving source structure where possible + +### Preconditions + +* A valid multi-file project exists +* Source mapping or section-origin context is available + +### Guarantees + +**Success** + +* A single review artifact is built from multiple sources +* Imported changes are either redistributed or clearly surfaced in fallback form +* Drift is reported with source-awareness where possible + +**Minimal** + +* Source structure is not silently lost + +### Main Success Scenario + +1. The actor inspects the multi-file project. +2. The actor validates the project. +3. The actor builds a single DOCX review artifact. +4. A reviewer edits the DOCX. +5. The actor imports the edited DOCX into the project context. +6. The system attempts source-aware redistribution. +7. The system either redistributes content or provides a managed fallback. +8. The actor runs drift comparison. +9. The system returns redistribution status and drift results. + +### Includes + +* UC-002 Inspect project configuration +* UC-003 Validate project readiness +* UC-004 Build DOCX review artifact +* UC-006 Import edited DOCX into Markdown +* UC-009 Redistribute imported edits to source files or UC-010 Fallback to merged Markdown import +* UC-011 Detect round-trip drift + +### Extensions + +* **6a.** Redistribution is ambiguous. + The system falls back to merged output and reports the condition. +* **8a.** Drift affects section boundaries or identifiers. + The system returns structural warnings. + +--- + +## UC-009 Redistribute imported edits to source files + +**Level:** User-goal +**Primary Actor:** Technical Editor +**Supporting Actors:** Source Mapping Context +**Goal:** Place imported content back into source-aligned Markdown outputs + +### Preconditions + +* A project-aware import result exists +* Source-origin metadata or equivalent mapping context exists + +### Guarantees + +**Success** + +* Imported content is redistributed into source-aligned outputs +* Redistribution status is reported + +**Minimal** + +* The system does not silently assign ambiguous content to incorrect sources + +### Main Success Scenario + +1. The actor requests source-aware redistribution of imported content. +2. The system loads source-origin mapping information. +3. The system associates imported sections with original source boundaries. +4. The system produces source-aligned Markdown outputs. +5. The system reports redistribution success and any warnings. + +### Extensions + +* **2a.** Required mapping information is missing. + The system reports redistribution cannot proceed safely. +* **3a.** An imported section matches multiple possible source boundaries. + The system flags the ambiguity. +* **4a.** Redistribution is only partially successful. + The system produces partial output and explicit warnings. + +### Related Use Cases + +* UC-010 Fallback to merged Markdown import + +--- + +## UC-010 Fallback to merged Markdown import + +**Level:** User-goal +**Primary Actor:** Technical Editor +**Goal:** Recover a usable Markdown result when source redistribution cannot be completed safely + +### Preconditions + +* An import result exists +* Safe redistribution is unavailable or ambiguous + +### Guarantees + +**Success** + +* A merged Markdown output is available +* The fallback condition is explicitly disclosed + +**Minimal** + +* Imported content is not lost + +### Main Success Scenario + +1. The system detects that source redistribution cannot be completed safely. +2. The system prepares a merged Markdown representation. +3. The system marks the result as fallback output. +4. The actor receives the merged Markdown and mapping warnings. + +### Extensions + +* **2a.** Import output itself is degraded. + The system returns fallback output with additional warning classification. + +--- + +## UC-011 Detect round-trip drift + +**Level:** User-goal +**Primary Actor:** Technical Editor +**Goal:** Compare original and imported document states and classify their differences + +### Preconditions + +* A baseline document state and an imported or alternate state exist + +### Guarantees + +**Success** + +* The actor receives a drift report +* Differences are classified into meaningful categories +* Structural changes are distinguished from cosmetic normalization + +**Minimal** + +* No compared content is modified + +### Main Success Scenario + +1. The actor requests drift comparison. +2. The system loads the baseline and comparison states. +3. The system compares the two states. +4. The system classifies detected differences. +5. The system reports comparison status and classified differences. + +### Extensions + +* **2a.** One of the compared states is unavailable. + The system reports comparison cannot proceed. +* **4a.** Broken references or citation issues are detected. + The system classifies them as structural or unresolved problems. + +### Related Use Cases + +* UC-022 Review warning and ambiguity report + +--- + +## UC-012 List available families + +**Level:** User-goal +**Primary Actor:** Template Administrator +**Goal:** Discover built-in and registered families + +### Preconditions + +* The system is operational + +### Guarantees + +**Success** + +* The actor receives a list of available families +* Built-in and registered families are visible with metadata + +**Minimal** + +* Registry state remains unchanged + +### Main Success Scenario + +1. The actor requests the family list. +2. The system retrieves available family registrations. +3. The system returns family identifiers and metadata summary. + +### Extensions + +* **2a.** Registry information is unavailable. + The system reports inability to provide the list. + +--- + +## UC-013 Register additional template family + +**Level:** User-goal +**Primary Actor:** Template Administrator +**Supporting Actors:** Template Registry +**Goal:** Add a new template/style family to the system + +### Preconditions + +* The actor has a candidate family definition and associated resources + +### Guarantees + +**Success** + +* The system accepts and registers the new family +* The family becomes discoverable for future use + +**Minimal** + +* Invalid registrations are not partially accepted without disclosure + +### Main Success Scenario + +1. The actor submits a new family registration. +2. The system validates the family definition and referenced resources. +3. The system checks compatibility declarations. +4. The system stores or activates the registration. +5. The system confirms successful registration. + +### Extensions + +* **2a.** The family definition is invalid. + The system rejects the registration with reasons. +* **3a.** Declared capabilities are inconsistent. + The system reports a validation error. +* **4a.** The family conflicts with an existing identifier. + The system reports a registration conflict. + +--- + +## UC-014 Build LEVEL1 document + +**Level:** User-goal +**Primary Actor:** Document Author +**Goal:** Process a document using LEVEL1 features + +### Preconditions + +* The project declares LEVEL1 or compatible capability +* The selected family supports LEVEL1 + +### Guarantees + +**Success** + +* The document is processed with support for headings, lists, tables, footnotes, images, and links + +**Minimal** + +* Unsupported non-LEVEL1 constructs are surfaced rather than silently accepted + +### Main Success Scenario + +1. The actor requests build or round-trip processing for a LEVEL1 project. +2. The system recognizes the declared feature level. +3. The system applies LEVEL1 support rules. +4. The system returns the resulting artifacts and/or reports. + +### Extensions + +* **2a.** The selected family does not support LEVEL1. + The system reports incompatibility. +* **3a.** Unsupported constructs are encountered. + The system reports warnings or failures as appropriate. + +--- + +## UC-015 Build LEVEL3 document + +**Level:** User-goal +**Primary Actor:** Technical Editor +**Goal:** Process a document using LEVEL3 features + +### Preconditions + +* The project declares LEVEL3 +* The selected family supports LEVEL3-related behaviors +* Supporting processors are available where needed + +### Guarantees + +**Success** + +* The document is processed with support for cross references, numbered figures, diagrams, and bibliography-aware workflows + +**Minimal** + +* Unsupported advanced features are surfaced explicitly + +### Main Success Scenario + +1. The actor requests build or round-trip processing for a LEVEL3 project. +2. The system recognizes the declared feature level. +3. The system resolves required supporting processors. +4. The system applies LEVEL3 support rules. +5. The system returns artifacts and reports. + +### Includes + +* UC-016 Generate automatic diagrams +* UC-017 Process bibliography-aware document + +### Extensions + +* **3a.** Required supporting processors are unavailable. + The system reports inability to complete full LEVEL3 processing. +* **4a.** Cross references or citations cannot be resolved safely. + The system reports unresolved advanced constructs. + +--- + +## UC-016 Generate automatic diagrams + +**Level:** Subfunction +**Primary Actor:** Document Author +**Supporting Actors:** Diagram Renderer +**Goal:** Include rendered diagrams derived from source declarations + +### Preconditions + +* The project includes diagram source declarations +* Diagram rendering capability is available + +### Guarantees + +**Success** + +* Diagram output is included in generated artifacts +* Diagram intent remains linked to its source representation within the managed workflow + +**Minimal** + +* Missing diagram support is explicitly reported + +### Main Success Scenario + +1. The system encounters a diagram source declaration during processing. +2. The system invokes diagram-capable processing. +3. The system includes the resulting rendered diagram in build output. +4. The system preserves the association between diagram source intent and rendered content. + +### Extensions + +* **2a.** The renderer is unavailable or fails. + The system reports the diagram processing problem. + +--- + +## UC-017 Process bibliography-aware document + +**Level:** Subfunction +**Primary Actor:** Technical Editor +**Supporting Actors:** Bibliography Processor +**Goal:** Process citations and bibliography in supported workflows + +### Preconditions + +* The project contains citation-bearing content or bibliography declarations + +### Guarantees + +**Success** + +* Citations and bibliography are included in supported output forms +* Round-trip ambiguities are surfaced when preservation cannot be guaranteed + +**Minimal** + +* Bibliography-related failures are explicitly reported + +### Main Success Scenario + +1. The system encounters citation-bearing content. +2. The system resolves bibliography-related inputs. +3. The system applies bibliography-aware processing. +4. The system includes citations and bibliography in generated output. +5. The system reports unresolved or ambiguous citation conditions when present. + +### Extensions + +* **2a.** Bibliography data is missing or unresolved. + The system reports bibliography-related issues. +* **3a.** Citation preservation cannot be guaranteed during import. + The system reports ambiguity. + +--- + +## UC-018 Execute local CLI workflow + +**Level:** Summary +**Primary Actor:** Build Operator +**Goal:** Use markidocx locally through the command-line interface + +### Preconditions + +* A local markidocx CLI is available +* Relevant project or artifact inputs are accessible + +### Guarantees + +**Success** + +* The actor can invoke core system functions locally +* The system returns human-readable and optionally structured outputs + +**Minimal** + +* Failed local operations produce explicit status information + +### Main Success Scenario + +1. The actor invokes a CLI command. +2. The system interprets the requested operation. +3. The system performs the underlying function. +4. The system returns status, outputs, warnings, and errors as applicable. + +### Variations + +* Validate project +* Build artifact +* Import DOCX +* Compare drift +* Inspect project +* List families +* Register family +* Run tests + +--- + +## UC-019 Execute REST-based workflow + +**Level:** Summary +**Primary Actor:** Integration Client +**Goal:** Use markidocx through the REST interface + +### Preconditions + +* The service is operational +* The client can submit project or artifact data + +### Guarantees + +**Success** + +* The client can invoke core system functions through REST +* The service returns structured machine-consumable results + +**Minimal** + +* Unsuccessful operations return explicit structured errors + +### Main Success Scenario + +1. The client submits a request to the service. +2. The system interprets the request. +3. The system performs the requested function. +4. The system returns a structured response with status and outputs. + +### Variations + +* Validate project +* Build artifact +* Import DOCX +* Compare drift +* List families +* Register family +* Retrieve capability metadata +* Retrieve health and version status + +--- + +## UC-020 Execute MCP-based workflow + +**Level:** Summary +**Primary Actor:** MCP Client +**Goal:** Use markidocx through MCP-discoverable tools and resources + +### Preconditions + +* An MCP-capable client is connected to the system +* The markidocx MCP interface is operational + +### Guarantees + +**Success** + +* The client can discover and invoke markidocx tools +* The client can retrieve project, capability, and result information + +**Minimal** + +* Unsupported tool requests are explicitly rejected or reported + +### Main Success Scenario + +1. The client discovers available markidocx tools and resources. +2. The client chooses a tool or resource. +3. The system performs the requested operation. +4. The system returns a structured tool result or resource content. + +### Variations + +* List templates/styles +* Inspect project +* Validate project +* Build DOCX +* Import DOCX +* Compare drift +* Run end-to-end tests +* Retrieve version metadata + +--- + +## UC-021 Run end-to-end regression on stable docs + +**Level:** User-goal +**Primary Actor:** Release Manager +**Goal:** Validate the latest stable markidocx documentation corpus as canonical end-to-end testcase + +### Preconditions + +* The latest stable documentation corpus exists as a managed markidocx project + +### Guarantees + +**Success** + +* The documentation corpus is processed through the required round-trip path +* The resulting validation evidence is available for release decisions + +**Minimal** + +* Failures are explicitly reported with usable evidence + +### Main Success Scenario + +1. The actor requests end-to-end regression execution. +2. The system loads the stable documentation corpus. +3. The system validates the documentation project. +4. The system builds required output artifacts. +5. The system performs import and comparison flows as defined by the regression profile. +6. The system records and reports regression outcomes. + +### Extensions + +* **3a.** The documentation project is no longer valid. + The system reports regression cannot proceed successfully. +* **5a.** Drift exceeds acceptable thresholds. + The system marks regression with warnings or failure. + +### Related Use Cases + +* UC-025 Build and inspect release evidence + +--- + +## UC-022 Review warning and ambiguity report + +**Level:** User-goal +**Primary Actor:** Technical Editor +**Goal:** Inspect unsupported, degraded, or ambiguous processing outcomes + +### Preconditions + +* A prior operation produced warnings or ambiguity results + +### Guarantees + +**Success** + +* The actor receives a structured explanation of detected issues +* The actor can distinguish unsupported from degraded but usable outcomes + +**Minimal** + +* The original operation result remains available + +### Main Success Scenario + +1. The actor opens or requests an operation report. +2. The system presents warnings, ambiguities, and severity classification. +3. The actor inspects the reported issues. +4. The actor uses the report to decide next steps. + +--- + +## UC-023 Retrieve system capability metadata + +**Level:** User-goal +**Primary Actor:** Integration Client +**Goal:** Discover what the system supports before invoking deeper operations + +### Preconditions + +* The system is operational + +### Guarantees + +**Success** + +* The actor receives capability metadata about supported feature levels, families, and interfaces + +**Minimal** + +* System state remains unchanged + +### Main Success Scenario + +1. The actor requests capability metadata. +2. The system gathers capability information. +3. The system returns a structured capability description. + +--- + +## UC-024 Retrieve health and version status + +**Level:** User-goal +**Primary Actor:** Build Operator +**Goal:** Determine whether the system is available and what version is running + +### Preconditions + +* The system or service endpoint is reachable + +### Guarantees + +**Success** + +* The actor receives health and version information + +**Minimal** + +* System state remains unchanged + +### Main Success Scenario + +1. The actor requests health or version information. +2. The system returns machine-consumable status information. + +--- + +## UC-025 Build and inspect release evidence + +**Level:** User-goal +**Primary Actor:** Release Manager +**Goal:** Produce auditable evidence of release-time round-trip behavior + +### Preconditions + +* A regression flow has been executed or is about to be executed + +### Guarantees + +**Success** + +* Build, import, validation, and drift evidence is assembled and inspectable +* Release decisions can reference the generated evidence + +**Minimal** + +* Missing evidence is explicitly reported + +### Main Success Scenario + +1. The actor requests release evidence generation or review. +2. The system collects relevant validation, build, import, and drift outputs. +3. The system assembles them into a coherent evidence set. +4. The actor reviews the evidence for release decision-making. + +--- + +# 8. Use Case Grouping by Functional Domain + +## 8.1 Project Lifecycle + +* UC-001 Define document project +* UC-002 Inspect project configuration +* UC-003 Validate project readiness + +## 8.2 Build and Template Workflow + +* UC-004 Build DOCX review artifact +* UC-005 Build using alternate family +* UC-012 List available families +* UC-013 Register additional template family + +## 8.3 Round-Trip Workflow + +* UC-006 Import edited DOCX into Markdown +* UC-007 Round-trip single-file document +* UC-008 Round-trip multi-file document +* UC-009 Redistribute imported edits to source files +* UC-010 Fallback to merged Markdown import +* UC-011 Detect round-trip drift +* UC-022 Review warning and ambiguity report + +## 8.4 Feature-Level Workflow + +* UC-014 Build LEVEL1 document +* UC-015 Build LEVEL3 document +* UC-016 Generate automatic diagrams +* UC-017 Process bibliography-aware document + +## 8.5 Interface Workflow + +* UC-018 Execute local CLI workflow +* UC-019 Execute REST-based workflow +* UC-020 Execute MCP-based workflow +* UC-023 Retrieve system capability metadata +* UC-024 Retrieve health and version status + +## 8.6 Release and Governance Workflow + +* UC-021 Run end-to-end regression on stable docs +* UC-025 Build and inspect release evidence + +--- + +# 9. Lifecycle Metadata Guidance + +Each use case in the managed catalog should support the following governance metadata: + +* **Status:** draft, active, deprecated, retired +* **Owner:** responsible role or team +* **Version introduced** +* **Last review date** +* **Trace links:** PRD sections, FRS IDs, test suites +* **Change note** + +Suggested default metadata model: + +```yaml +use_case: + id: UC-004 + name: Build DOCX review artifact + status: active + owner: product-management + version_introduced: "1.0" + last_review: "2026-03-14" + traces: + prd: + - "Section 6 Product Use Cases" + - "Section 8 Success Criteria" + frs: + - "FR-201" + - "FR-203" + - "FR-204" + - "FR-208" + tests: + - "E2E-BUILD-001" + - "CLI-BUILD-001" + - "REST-BUILD-001" +``` + +--- + +# 10. Suggested Traceability Anchors to FRS + +## Project and Manifest + +* UC-001 ↔ FR-101 to FR-106 +* UC-002 ↔ FR-104 to FR-105 +* UC-003 ↔ FR-701 to FR-703 + +## Build and Export + +* UC-004 ↔ FR-201 to FR-209 +* UC-005 ↔ FR-204 to FR-205, FR-603 to FR-610 + +## Import and Round-Trip + +* UC-006 ↔ FR-301 to FR-308 +* UC-007 ↔ FR-201 to FR-308, FR-704 to FR-710 +* UC-008 ↔ FR-401 to FR-407, FR-704 to FR-710 +* UC-009 ↔ FR-404 to FR-407 +* UC-010 ↔ FR-406 +* UC ↔ FR-704 to FR-710 +* UC-022 ↔ FR-1202 to FR-1205 + +## Feature Levels + +* UC-014 ↔ FR-501 to FR-506 +* UC-015 ↔ FR-531 to FR-537 +* UC-016 ↔ FR-533 to FR-534 +* UC-017 ↔ FR-535 to FR-536 + +## Interfaces + +* UC-018 ↔ FR-801 to FR-812 +* UC-019 ↔ FR-901 to FR-912 +* UC-020 ↔ FR-1001 to FR-1011 +* UC-023 ↔ FR-909, FR-1011 +* UC-024 ↔ FR-910 to FR-911 + +## Release and Testing + +* UC-021 ↔ FR-1101 to FR-1106 +* UC-025 ↔ FR-1106, FR-701 to FR-710 + +--- + +# 11. Optional Machine-Readable UCC Example + +```yse: + id: UC-008 + name: Round-trip multi-file document + scope: markidocx + level: summary + + primary_actor: Technical Editor + supporting_actors: + - Source Mapping Context + + preconditions: + - A valid multi-file project exists + - Source mapping or section-origin context is available + + guarantees: + success: + - A single review artifact is built from multiple sources + - Imported changes are either redistributed or clearly surfaced in fallback form + - Drift is reported with source-awareness where possible + minimal: + - Source structure is not silently lost + + main_success_scenario: + - Actor inspects the multi-file project + - Actor validates the project + - Actor builds a single DOCX review artifact + - Reviewer edits the DOCX + - Actor imports the edited DOCX into the project context + - System attempts source-aware redistribution + - System either redistributes content or provides a managed fallback + - Actor runs drift comparison + - System returns redistribution status and drift results + + extensions: + - step: 6 + condition: redistribution is ambiguous + outcome: system falls back to merged output and reports the condition + - step: 8 + condition: drift affects section boundaries or identifiers + outcome: system returns structural warnings + + includes: + - UC-002 + - UC-003 + - UC-004 + - UC-006 + - UC-011 + + status: draft + owner: product-management + last_review: 2026-03-14 +``` + +--- + +# 12. Concise Summary + +This UCC gives markidocx a proper **actor-goal-centered functional backbone**. It expands the earlier use cases into a governed catalog that can now serve as the bridge between: + +* PRD intent +* FRS requirement groups +* acceptance test design +* later API and schema contracts + +The strongest next step is to derive either: + +1. an **acceptance criteria catalog** from these use cases, or +2. a **machine-readable UCC schema pack** with one YAML file per use case plus an index manifest. + +xxx diff --git a/src/markidocx/__init__.py b/src/markidocx/__init__.py new file mode 100644 index 0000000..b2b9cd7 --- /dev/null +++ b/src/markidocx/__init__.py @@ -0,0 +1,3 @@ +"""markidocx — Markdown ↔ DOCX round-trip editing system.""" + +__version__ = "0.1.0" diff --git a/src/markidocx/cli.py b/src/markidocx/cli.py new file mode 100644 index 0000000..94d5b0b --- /dev/null +++ b/src/markidocx/cli.py @@ -0,0 +1,261 @@ +"""CLI entry point for markidocx.""" + +from __future__ import annotations + +import json +import sys +from pathlib import Path +from typing import Annotated, Optional + +import typer +from rich.console import Console +from rich.table import Table + +app = typer.Typer( + name="markidocx", + help="Markdown ↔ DOCX round-trip editing system.", + add_completion=False, +) +template_app = typer.Typer(help="Template family management.") +app.add_typer(template_app, name="template") + +console = Console() +err_console = Console(stderr=True) + + +@app.command() +def validate( + manifest: Annotated[Path, typer.Argument(help="Path to manifest YAML file")], + json_output: Annotated[bool, typer.Option("--json", help="Machine-readable JSON output")] = False, +) -> None: + """Validate a manifest file (FR-100).""" + from markidocx.manifest import ManifestError, load_manifest + + try: + m = load_manifest(manifest) + if json_output: + typer.echo(json.dumps({"status": "ok", "project": m.project.name})) + else: + console.print(f"[green]✓[/green] Manifest valid: [bold]{m.project.name}[/bold]") + raise typer.Exit(0) + except ManifestError as exc: + if json_output: + typer.echo(json.dumps({"status": "error", "message": str(exc)})) + else: + err_console.print(f"[red]✗ Manifest error:[/red] {exc}") + raise typer.Exit(1) + + +@app.command() +def build( + manifest: Annotated[Path, typer.Argument(help="Path to manifest YAML file")], + json_output: Annotated[bool, typer.Option("--json", help="Machine-readable JSON output")] = False, +) -> None: + """Build a DOCX from Markdown sources (FR-200).""" + from markidocx.builder import build_document + from markidocx.manifest import ManifestError, load_manifest + + try: + m = load_manifest(manifest) + except ManifestError as exc: + if json_output: + typer.echo(json.dumps({"status": "error", "message": str(exc)})) + else: + err_console.print(f"[red]✗ Manifest error:[/red] {exc}") + raise typer.Exit(1) + + result = build_document(m) + if json_output: + typer.echo( + json.dumps( + { + "status": "ok" if result.success else "error", + "output_path": str(result.output_path), + "family": result.family, + "feature_level": result.feature_level, + "warnings": result.warnings, + "errors": result.errors, + } + ) + ) + else: + if result.success: + console.print(f"[green]✓[/green] Built: [bold]{result.output_path}[/bold]") + for w in result.warnings: + console.print(f"[yellow]⚠[/yellow] {w}") + else: + for e in result.errors: + err_console.print(f"[red]✗[/red] {e}") + + raise typer.Exit(0 if result.success else 1) + + +@app.command("import") +def import_docx( + manifest: Annotated[Path, typer.Argument(help="Path to manifest YAML file")], + docx: Annotated[Path, typer.Argument(help="Path to DOCX file to import")], + json_output: Annotated[bool, typer.Option("--json", help="Machine-readable JSON output")] = False, +) -> None: + """Import a DOCX back to Markdown (FR-300).""" + from markidocx.importer import import_document + from markidocx.manifest import ManifestError, load_manifest + + try: + m = load_manifest(manifest) + except ManifestError as exc: + if json_output: + typer.echo(json.dumps({"status": "error", "message": str(exc)})) + else: + err_console.print(f"[red]✗ Manifest error:[/red] {exc}") + raise typer.Exit(1) + + result = import_document(m, docx) + if json_output: + typer.echo( + json.dumps( + { + "status": "ok" if result.success else "error", + "output_files": [str(p) for p in result.output_files], + "mapping_status": result.mapping_status, + "warnings": result.warnings, + } + ) + ) + else: + if result.success: + console.print(f"[green]✓[/green] Imported ({result.mapping_status})") + for f in result.output_files: + console.print(f" → {f}") + for w in result.warnings: + console.print(f"[yellow]⚠[/yellow] {w}") + else: + err_console.print("[red]✗ Import failed[/red]") + + raise typer.Exit(0 if result.success else 1) + + +@app.command() +def compare( + manifest: Annotated[Path, typer.Argument(help="Path to manifest YAML file")], + docx: Annotated[Path, typer.Argument(help="Path to DOCX file to compare against")], + json_output: Annotated[bool, typer.Option("--json", help="Machine-readable JSON output")] = False, +) -> None: + """Compare original Markdown with re-imported DOCX (FR-700).""" + from markidocx.builder import build_document + from markidocx.differ import compare as do_compare + from markidocx.importer import import_document + from markidocx.manifest import ManifestError, load_manifest + + try: + m = load_manifest(manifest) + except ManifestError as exc: + if json_output: + typer.echo(json.dumps({"status": "error", "message": str(exc)})) + else: + err_console.print(f"[red]✗ Manifest error:[/red] {exc}") + raise typer.Exit(2) + + # Read original markdown + original_parts: list[str] = [] + for src in m.sources: + p = manifest.parent / src.path + original_parts.append(p.read_text(encoding="utf-8")) + original_md = "\n\n".join(original_parts) + + # Import the docx + result = import_document(m, docx) + if not result.success: + if json_output: + typer.echo(json.dumps({"status": "error", "message": "Import failed"})) + else: + err_console.print("[red]✗ Import failed — cannot compare[/red]") + raise typer.Exit(2) + + reimported_parts: list[str] = [] + for f in result.output_files: + reimported_parts.append(Path(f).read_text(encoding="utf-8")) + reimported_md = "\n\n".join(reimported_parts) + + report = do_compare(original_md, reimported_md) + + if json_output: + typer.echo( + json.dumps( + { + "has_drift": report.has_drift, + "preserved": report.preserved, + "degraded": report.degraded, + "broken": report.broken, + "unsupported": report.unsupported, + } + ) + ) + else: + if report.has_drift: + console.print("[yellow]⚠ Drift detected[/yellow]") + for item in report.degraded: + console.print(f" [yellow]degraded:[/yellow] {item}") + for item in report.broken: + console.print(f" [red]broken:[/red] {item}") + else: + console.print("[green]✓[/green] No drift detected") + if report.preserved: + console.print(f" preserved: {len(report.preserved)} elements") + + raise typer.Exit(1 if report.has_drift else 0) + + +@template_app.command("list") +def template_list( + json_output: Annotated[bool, typer.Option("--json", help="Machine-readable JSON output")] = False, +) -> None: + """List available template families (FR-603).""" + from markidocx.templates import FamilyRegistry + + registry = FamilyRegistry() + families = registry.list_families() + + if json_output: + typer.echo( + json.dumps( + [{"name": f.name, "description": f.description} for f in families] + ) + ) + else: + table = Table(title="Template Families") + table.add_column("Name", style="bold") + table.add_column("Description") + for f in families: + table.add_row(f.name, f.description) + console.print(table) + + +@template_app.command("register") +def template_register( + path: Annotated[Path, typer.Argument(help="Path to .docx template")], + name: Annotated[str, typer.Option("--name", help="Family name")] = "", + description: Annotated[str, typer.Option("--description", help="Family description")] = "", + json_output: Annotated[bool, typer.Option("--json", help="Machine-readable JSON output")] = False, +) -> None: + """Register a custom template family (FR-605).""" + from markidocx.templates import FamilyRegistry + + registry = FamilyRegistry() + if not name: + name = path.stem + try: + registry.register(path, name, description) + if json_output: + typer.echo(json.dumps({"status": "ok", "name": name})) + else: + console.print(f"[green]✓[/green] Registered template: [bold]{name}[/bold]") + except Exception as exc: + if json_output: + typer.echo(json.dumps({"status": "error", "message": str(exc)})) + else: + err_console.print(f"[red]✗[/red] {exc}") + raise typer.Exit(1) + + +if __name__ == "__main__": + app() diff --git a/tests/__init__.py b/tests/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/conftest.py b/tests/conftest.py new file mode 100644 index 0000000..611e4e3 --- /dev/null +++ b/tests/conftest.py @@ -0,0 +1,63 @@ +"""Shared test fixtures for markidocx tests.""" + +from __future__ import annotations + +import textwrap +from pathlib import Path + +import pytest + + +SIMPLE_MARKDOWN = textwrap.dedent("""\ + # Hello World + + This is a paragraph with **bold** and *italic* text. + + ## Section One + + - Item one + - Item two + - Item three + + ### Subsection + + Some text with a [link](https://example.com) and `inline code`. + + ## Section Two + + | Column A | Column B | Column C | + |----------|----------|----------| + | row1a | row1b | row1c | + | row2a | row2b | row2c | + + 1. First ordered item + 2. Second ordered item + 3. Third ordered item +""") + +SIMPLE_MANIFEST_YAML = textwrap.dedent("""\ + project: + name: "Test Document" + feature_level: level1 + family: article + + sources: + - path: doc.md + + output: + dir: ./dist + + metadata: + title: "Test Document" + author: "Test Author" + date: "2026-01-01" +""") + + +@pytest.fixture() +def tmp_project(tmp_path: Path) -> Path: + """Create a minimal project directory with a manifest and source file.""" + (tmp_path / "doc.md").write_text(SIMPLE_MARKDOWN, encoding="utf-8") + (tmp_path / "manifest.yaml").write_text(SIMPLE_MANIFEST_YAML, encoding="utf-8") + (tmp_path / "dist").mkdir() + return tmp_path diff --git a/workplans/MRKD-WP-0001-foundation-level1.md b/workplans/MRKD-WP-0001-foundation-level1.md new file mode 100644 index 0000000..b9a9796 --- /dev/null +++ b/workplans/MRKD-WP-0001-foundation-level1.md @@ -0,0 +1,191 @@ +--- +id: MRKD-WP-0001 +type: workplan +domain: markitect +repo: marki-docx +status: active +state_hub_workstream_id: de855681-7ce0-4ace-b283-ec61f7557066 +created: 2026-03-14 +updated: 2026-03-14 +--- + +# MRKD-WP-0001 — Foundation & LEVEL1 Core + +Build the markidocx Python package from scratch through a working LEVEL1 round-trip CLI. +This workstream covers all functional prerequisites: package scaffolding, manifest model, +MD→DOCX build, DOCX→MD import, three template family stubs, validation + drift detection, +and an end-to-end regression harness using the specs as the test corpus. + +**Scope:** FR-100, FR-200, FR-300, FR-400, FR-500 (LEVEL1), FR-600 (stubs), FR-700, FR-800, FR-1100 +**Out of scope:** REST service (FR-900), MCP tools (FR-1000), LEVEL3 features (FR-531–542) + +--- + +## T01 — Project scaffolding + +```task +id: MRKD-WP-0001-T01 +status: todo +priority: high +state_hub_task_id: 5dd0e377-2a4e-4ddd-a6fa-aeb097ead292 +``` + +Set up the Python package: `pyproject.toml`, `src/markidocx/` layout, ruff + mypy config, +pytest, pre-commit hooks, and CI skeleton. No functional code — just a working dev environment. + +Deliverable: `pip install -e ".[dev]"` works, `pytest` collects 0 tests without error, +`ruff check .` and `mypy src/` exit clean. + +--- + +## T02 — Manifest model (FR-100) + +```task +id: MRKD-WP-0001-T02 +status: todo +priority: high +state_hub_task_id: d381a578-821a-44f0-b1a2-5254966aae48 +``` + +Define the project manifest schema (YAML): source files, feature level, template/style family, +document metadata. Implement FR-101–110: + +- Parse and validate a manifest file +- Detect missing referenced resources (FR-103) +- Expose project inspection and capability disclosure (FR-104, FR-105) +- Warn on unsupported configuration (FR-106) +- Report resolution status (FR-109) + +Deliverable: `markidocx validate ` exits 0 on valid, 1 on error, 2 on warnings. + +--- + +## T03 — LEVEL1 build / MD→DOCX export (FR-200, FR-501–508) + +```task +id: MRKD-WP-0001-T03 +status: todo +priority: high +state_hub_task_id: 2c466852-d136-48cf-ba53-8c999f11527e +``` + +Implement Markdown composition and DOCX export at LEVEL1 feature coverage: + +- Headings (FR-501), lists (FR-502), tables (FR-503), footnotes (FR-504), + images (FR-506), links (FR-506) +- Template application (FR-204), metadata propagation (FR-207) +- Build result reporting: success/warning/failure, artifact path, family + feature-level + disclosure (FR-208–211) +- Surface unsupported constructs explicitly rather than silently accepting them (FR-508) + +Deliverable: `markidocx build ` produces a valid DOCX for a LEVEL1 document. + +--- + +## T04 — LEVEL1 import / DOCX→MD round-trip (FR-300, FR-400) + +```task +id: MRKD-WP-0001-T04 +status: todo +priority: high +state_hub_task_id: 117a5de0-eeef-4358-8c78-fed26ae55f2b +``` + +Implement DOCX import with project-aware context: + +- Markdown reconstitution at LEVEL1 (FR-303, FR-304) +- Source redistribution for multi-file projects using source mapping (FR-305, FR-405) +- Fallback merged output when redistribution cannot complete safely (FR-406) +- Import result and mapping status reporting (FR-306, FR-311, FR-312) +- Section boundary integrity reporting (FR-407) + +Deliverable: `markidocx import ` writes redistributed Markdown +files (or fallback merge) and exits with structured status. + +--- + +## T05 — Template & style family stubs: article, book, website (FR-600) + +```task +id: MRKD-WP-0001-T05 +status: todo +priority: medium +state_hub_task_id: 3d10a43b-301d-4717-9ab4-f43851058c3f +``` + +Create the three built-in DOCX template families (`article`, `book`, `website`) with +matching style definitions. Families need not be fully designed — structurally correct +for LEVEL1 is sufficient. + +- Family metadata and discovery (FR-602, FR-603, FR-604) +- Template registration and paired-family registration (FR-605, FR-606, FR-607) +- Registration validation (FR-608) + +Deliverable: `markidocx template list` returns all three families; each produces a +valid DOCX when used in a build. + +--- + +## T06 — Validation & drift detection (FR-700) + +```task +id: MRKD-WP-0001-T06 +status: todo +priority: medium +state_hub_task_id: 0390f7d3-a9c3-4cac-a295-303adfe82960 +``` + +Implement structural diff between baseline Markdown and re-imported result: + +- Compare heading hierarchy, list structure, table presence, footnotes, links +- Classify each construct as preserved / degraded / broken / unsupported +- Produce a drift report as an inspectable evidence artefact (JSON + human-readable) + +Deliverable: `markidocx compare ` exits 0 (no drift), +1 (drift detected), or 2 (comparison failed), and writes a drift report. + +--- + +## T07 — CLI interface (FR-800) + +```task +id: MRKD-WP-0001-T07 +status: todo +priority: medium +state_hub_task_id: 2e455d87-9044-411e-91c7-3a512488904a +``` + +Wire the functional core to a CLI entry point. Commands: + +| Command | Maps to | +|---------|---------| +| `markidocx build ` | FR-200 build | +| `markidocx import ` | FR-300 import | +| `markidocx compare ` | FR-700 drift | +| `markidocx validate ` | FR-100 resolution | +| `markidocx template list` | FR-603 | +| `markidocx template register ` | FR-605 | + +Machine-readable output flag (`--json`). Exit codes: 0 success, 1 error, 2 warning (per FR-1200). + +--- + +## T08 — End-to-end test harness & regression corpus (FR-1100) + +```task +id: MRKD-WP-0001-T08 +status: todo +priority: medium +state_hub_task_id: ca3ecede-aef3-48b0-b21b-2b9f59167cb5 +``` + +Build the round-trip regression harness using the markidocx specs as the test corpus +(per the FRS intent that product documentation serves as a stable validation corpus): + +- `build → import → compare` cycle for each spec document at LEVEL1 +- Per-family smoke tests (article, book, website) +- Drift-detection assertions: zero structural drift expected on a clean round-trip +- CI-runnable with `pytest` + +Deliverable: `pytest tests/regression/` passes on a clean round-trip; drift regressions +cause test failures.