generated from coulomb/repo-seed
chore: workplan MRKD-WP-0001 + improved CLAUDE.md; document next steps
- 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 <noreply@anthropic.com>
This commit is contained in:
88
CLAUDE.md
88
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 <manifest.yaml>
|
||||
|
||||
# CLI: import an edited DOCX
|
||||
markidocx import <manifest.yaml> <edited.docx>
|
||||
|
||||
# CLI: compare baseline vs re-import
|
||||
markidocx compare <manifest.yaml> <edited.docx>
|
||||
|
||||
# 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.
|
||||
|
||||
76
problems/next-steps-2026-03-14.md
Normal file
76
problems/next-steps-2026-03-14.md
Normal file
@@ -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
|
||||
53
pyproject.toml
Normal file
53
pyproject.toml
Normal file
@@ -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"
|
||||
737
specs/MarkiDocxFunctionalRequirementsSpecification_v0.1.md
Normal file
737
specs/MarkiDocxFunctionalRequirementsSpecification_v0.1.md
Normal file
@@ -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
|
||||
1191
specs/MarkiDocxFunctionalRequirementsSpecification_v0.2.md
Normal file
1191
specs/MarkiDocxFunctionalRequirementsSpecification_v0.2.md
Normal file
File diff suppressed because it is too large
Load Diff
391
specs/MarkiDocxProductRequirementsDocument_v0.1.md
Normal file
391
specs/MarkiDocxProductRequirementsDocument_v0.1.md
Normal file
@@ -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
|
||||
1412
specs/MarkiDocxUseCaseCatalog_v0.1.md
Normal file
1412
specs/MarkiDocxUseCaseCatalog_v0.1.md
Normal file
File diff suppressed because it is too large
Load Diff
3
src/markidocx/__init__.py
Normal file
3
src/markidocx/__init__.py
Normal file
@@ -0,0 +1,3 @@
|
||||
"""markidocx — Markdown ↔ DOCX round-trip editing system."""
|
||||
|
||||
__version__ = "0.1.0"
|
||||
261
src/markidocx/cli.py
Normal file
261
src/markidocx/cli.py
Normal file
@@ -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()
|
||||
0
tests/__init__.py
Normal file
0
tests/__init__.py
Normal file
63
tests/conftest.py
Normal file
63
tests/conftest.py
Normal file
@@ -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
|
||||
191
workplans/MRKD-WP-0001-foundation-level1.md
Normal file
191
workplans/MRKD-WP-0001-foundation-level1.md
Normal file
@@ -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 <manifest.yaml>` 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 <manifest.yaml>` 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 <manifest.yaml> <edited.docx>` 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 <manifest.yaml> <edited.docx>` 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 <manifest>` | FR-200 build |
|
||||
| `markidocx import <manifest> <docx>` | FR-300 import |
|
||||
| `markidocx compare <manifest> <docx>` | FR-700 drift |
|
||||
| `markidocx validate <manifest>` | FR-100 resolution |
|
||||
| `markidocx template list` | FR-603 |
|
||||
| `markidocx template register <path>` | 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.
|
||||
Reference in New Issue
Block a user