coulomb/marki-docx
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: workplan MRKD-WP-0001 + improved CLAUDE.md; document next steps

Browse Source 
- 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:
Bernd Worsch
2026-03-14 18:18:54 +01:00
parent d298e2989d
commit c6dfc9b172
12 changed files with 4465 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

737
specs/MarkiDocxFunctionalRequirementsSpecification_v0.1.md Normal file
View 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