marki-docx/specs/MarkiDocxFunctionalRequirementsSpecification_v0.2.md

FRS

Functional Requirements Specification

Functional Requirements Specification: markidocx

Version: v0.2 Status: Draft Supersedes: Previous draft FRS for markidocx Related Artifacts: PRD markidocx, UCC markidocx

---

1. Definition

This Functional Requirements Specification defines the externally observable behaviors and required functions of markidocx, a system for controlled Markdown ↔ DOCX round-trip editing.

The FRS specifies what markidocx must do from the perspective of users, external systems, and exposed interfaces. It defines required functions for:

• document build and export
• document import and reconstitution
• multi-file composition
• template and style management
• feature-level document processing
• validation and drift reporting
• local CLI usage
• REST-based service interaction
• MCP-based tool interaction
• end-to-end regression execution
• composite workflow execution
• evidence and report management

This FRS is derived from the markidocx PRD and aligned with the markidocx UCC. It serves as the binding functional contract for implementation and acceptance.

---

2. Context

markidocx is intended to support documentation workflows in which:

• structured content is maintained in Markdown
• editorial review is performed in Microsoft Word
• document generation must be repeatable and inspectable
• multiple stakeholders and systems interact with the same documentation assets

The system acts as a functional bridge between:

• canonical Markdown source documents
• Word-based review artifacts
• automated documentation pipelines
• external tools and agents

Functionally, the system must allow content to move between these contexts while preserving supported structure and surfacing any drift or ambiguity introduced during the process.

The UCC establishes actor-goal-centered workflows for this system. This FRS translates those workflows into precise functional expectations while remaining independent of architecture and implementation.

---

3. Core Concepts

3.1 System Function

A system function is a user-visible or interface-visible capability the system provides, such as building a DOCX artifact, importing an edited document, validating a template registration, or assembling release evidence.

3.2 Externally Observable Behavior

Externally observable behavior includes all results visible through the CLI, REST interface, MCP interface, output artifacts, reports, and return statuses.

3.3 Requirement Statement

Each requirement in this document is written as a declarative, testable statement describing required system behavior.

3.4 Input–Output Relationship

markidocx receives manifests, Markdown sources, templates, styles, DOCX files, and configuration inputs and produces artifacts, reports, validation outcomes, and structured metadata.

3.5 Traceability

The requirements in this FRS are intended to trace back to the markidocx PRD and UCC and forward into implementation, interface contracts, and validation suites.

3.6 Composite Workflow

A composite workflow is a system-supported sequence of lower-level functions that together fulfill a meaningful actor goal, such as a full round-trip cycle or end-to-end regression run.

3.7 Functional Evidence

Functional evidence is an inspectable set of outputs produced by validation, build, import, comparison, or regression functions and usable for acceptance, audit, or release decisions.

---

4. Scope and Non-Scope

In Scope

This FRS covers:

• functional system behavior
• user-facing and interface-facing commands and operations
• supported document processing behavior
• interface-level interactions through CLI, REST, and MCP
• functional handling of templates, styles, manifests, and artifacts
• conditions under which functions succeed, warn, fall back, or fail
• report and evidence generation as externally visible behavior
• workflow-level orchestration where exposed as a system function

Out of Scope

This FRS does not define:

• internal architecture
• code organization
• algorithms or parser strategies
• storage implementation
• UI layout
• deployment topology
• performance or security design except where behaviorally relevant

---

5. System Overview

markidocx shall provide a functional workflow in which a user or external system can:

1. define a document project using Markdown sources and a manifest
2. compose one or more Markdown files into a document model
3. export that document into DOCX using a selected template/style family
4. import an edited DOCX back into Markdown form
5. validate compatibility and structural integrity
6. detect and report drift between baseline and re-imported forms
7. manage template/style families
8. access the same capabilities locally, via service calls, or through MCP tools
9. run end-to-end tests using the latest stable markidocx documentation corpus
10. invoke composite workflows for common round-trip scenarios
11. assemble inspectable evidence from validation and regression flows

---

6. Functional Requirements Structure

Requirements are grouped into the following domains:

• FR-100 Project and manifest management
• FR-200 Build and export
• FR-300 Import and round-trip processing
• FR-400 Multi-file document handling
• FR-500 Feature level support
• FR-600 Template and style management
• FR-700 Validation and drift analysis
• FR-800 CLI functions
• FR-900 REST service functions
• FR-1000 MCP functions
• FR-1100 Test and regression functions
• FR-1200 Error and warning behavior
• FR-1300 Composite workflow functions
• FR-1400 Evidence and report management

---

7. Functional Requirements

7.1 Project and Manifest Management

FR-101 Project Manifest Recognition

The system shall accept a project definition that identifies the document project, its source files, document type, feature level, and associated template/style selections.

FR-102 Manifest Validation

The system shall determine whether a provided project manifest is syntactically and functionally valid.

FR-103 Missing Resource Detection

The system shall report an error when a manifest references a source, asset, bibliography, template, or style that is not available.

FR-104 Project Inspection

The system shall provide a way to inspect the resolved project configuration, including source ordering, selected feature level, template selection, and derived document metadata.

FR-105 Project Capability Disclosure

The system shall expose the effective capabilities of a project as derived from the manifest and registered feature support.

FR-106 Unsupported Manifest Configuration Detection

The system shall reject or warn on manifest settings that are inconsistent with supported system behavior.

FR-107 Project Context Reuse

The system shall support reuse of a project definition across build, import, validation, comparison, and test operations.

FR-108 Project Context Identity

The system shall expose sufficient project identity information to associate outputs and reports with the project from which they were derived.

FR-109 Project Resolution Status Reporting

The system shall report whether project resolution completed successfully, completed with warnings, or failed.

FR-110 Project Input Scope Disclosure

The system shall disclose which declared source files, assets, bibliography inputs, and family references are effectively in scope for a given project operation.

---

7.2 Build and Export

FR-201 Build Invocation

The system shall allow a user or external client to request document build/export for a defined project.

FR-202 Markdown Composition

The system shall compose the project’s declared Markdown sources into a buildable document representation.

FR-203 DOCX Export

The system shall generate a DOCX artifact from a valid project when DOCX output is requested.

FR-204 Template Application

The system shall apply the selected DOCX template family during DOCX generation.

FR-205 Style Selection

The system shall associate the selected style family with the generated output where relevant to the output mode.

FR-206 Asset Inclusion

The system shall include referenced images and other supported assets in the exported document where the asset is valid and resolvable.

FR-207 Metadata Propagation

The system shall propagate supported document metadata from project inputs into the generated document.

FR-208 Build Result Reporting

The system shall return a structured build result indicating success, warnings, or failure and identify generated artifacts.

FR-209 Deterministic Build Result Disclosure

The system shall provide build output metadata sufficient for later validation and comparison.

FR-210 Build Family Disclosure

The system shall identify in the build result which template/style family was applied.

FR-211 Build Feature-Level Disclosure

The system shall identify in the build result which feature level was applied.

FR-212 Alternate Output Compatibility Reporting

When the same source is built under different compatible families, the system shall report each build result independently without implying semantic changes to the source content.

FR-213 Build Degradation Reporting

When a build completes with degraded treatment of supported or optional content, the system shall disclose the degradation in the build result.

FR-214 Build Preconditions Reference

The system shall allow build results to reference or embed the validation state relevant to the build where such state is available.

---

7.3 Import and Round-Trip Processing

FR-301 DOCX Import Invocation

The system shall allow a user or external client to submit a DOCX document for import into Markdown-compatible project form.

FR-302 Project-Aware Import

The system shall import DOCX content in the context of a specified project configuration when such context is provided.

FR-303 Markdown Reconstitution

The system shall produce Markdown output from the imported DOCX for supported constructs.

FR-304 Structural Preservation

The system shall preserve supported document structure during import within the bounds of the selected feature level.

FR-305 Source Mapping Use

When project source mapping is available, the system shall use it to associate imported content with original source boundaries.

FR-306 Import Result Reporting

The system shall report the result of an import operation, including generated outputs, warnings, and identified ambiguities.

FR-307 Unsupported Construct Reporting

The system shall explicitly report Word constructs that cannot be safely mapped into supported Markdown representation.

FR-308 Re-import Equivalence Support

The system shall support round-trip workflows in which exported DOCX documents can be re-imported into semantically equivalent Markdown representations, subject to supported feature classes and accepted normalization.

FR-309 Import Context Disclosure

The system shall disclose whether an import was performed with or without project-aware context.

FR-310 Redistribution Attempt Disclosure

The system shall disclose whether source-aware redistribution was attempted during project-aware import.

FR-311 Import Mapping Status

The system shall disclose whether imported content was source-aligned, partially source-aligned, merged as fallback, or imported without source alignment.

FR-312 Partial Import Result Reporting

The system shall report when import produced only partial usable output.

FR-313 Import Preservation Scope Disclosure

The system shall disclose which supported structures were preserved, degraded, unresolved, or unsupported in a given import operation.

FR-314 Import Reviewability

The system shall provide import outputs and reports in a form that allows a user or client to inspect the relation between source context and imported result.

---

7.4 Multi-File Document Handling

FR-401 Multi-File Source Declaration

The system shall support projects consisting of multiple Markdown source files.

FR-402 Ordered Composition

The system shall preserve declared source ordering when composing a multi-file document.

FR-403 Whole-Document Export

The system shall support export of a multi-file project into a single reviewable document artifact.

FR-404 Source-Origin Awareness

The system shall maintain source-origin information sufficient to support round-trip handling of multi-file documents.

FR-405 Source Redistribution

The system shall support redistribution of imported content back into source-aligned outputs when source mapping information is available.

FR-406 Fallback Import Form

When source redistribution cannot be completed safely, the system shall provide a valid merged Markdown result and indicate the fallback condition.

FR-407 Section Boundary Integrity Reporting

The system shall report when imported edits cause ambiguity or breakage at tracked source or section boundaries.

FR-408 Partial Redistribution Reporting

The system shall report when redistribution succeeds only for a subset of imported content.

FR-409 Redistribution Failure Reason Disclosure

The system shall disclose why source redistribution could not be completed safely.

FR-410 Redistribution Outcome Classification

The system shall classify redistribution outcomes as successful, partial, ambiguous, or failed.

FR-411 Source-Boundary Preservation Disclosure

The system shall disclose whether tracked source boundaries were preserved, blurred, or broken during import and redistribution processing.

FR-412 Fallback Output Identification

The system shall identify fallback merged outputs as fallback artifacts rather than ordinary source-aligned results.

---

7.5 Feature Level Support

7.5.1 LEVEL1

FR-501 Heading Support

The system shall export and import heading structures and preserve supported heading hierarchy.

FR-502 List Support

The system shall export and import ordered and unordered lists and preserve list structure within supported cases.

FR-503 Table Support

The system shall export and import supported table structures.

FR-504 Footnote Support

The system shall export and import footnotes and preserve their association with referencing content.

FR-505 Image Support

The system shall export and import supported images and preserve image references and associated descriptive metadata where available.

FR-506 Link Support

The system shall export and import links and preserve supported link targets and visible text.

FR-507 LEVEL1 Processing Disclosure

The system shall disclose when a document is processed under LEVEL1 expectations.

FR-508 LEVEL1 Unsupported Construct Visibility

When constructs outside supported LEVEL1 scope are encountered in a LEVEL1 workflow, the system shall surface them explicitly rather than silently accepting them as preserved.

7.5.2 LEVEL3

FR-531 Cross-Reference Support

The system shall support export and import workflows for supported cross references between labeled content elements.

FR-532 Numbered Figure Support

The system shall support export of figures with captions and numbering and preserve figure identity sufficiently for supported round-trip usage.

FR-533 Automatic Diagram Support

The system shall support diagrams derived from source declarations as part of document build/export workflows.

FR-534 Diagram Intent Preservation

The system shall preserve the connection between diagram source intent and rendered output within the managed workflow.

FR-535 Bibliography Support

The system shall support bibliography-aware document generation from structured citation inputs.

FR-536 Citation Preservation

The system shall preserve supported citation semantics during round-trip processing or report when ambiguity prevents safe preservation.

FR-537 Feature-Level Compatibility Disclosure

The system shall disclose whether a project, template family, or processing path supports LEVEL1 only or LEVEL3.

FR-538 LEVEL3 Processor Dependency Disclosure

The system shall disclose when LEVEL3 processing depends on additional supporting processors or tools.

FR-539 LEVEL3 Partial Support Reporting

The system shall report when a requested LEVEL3 workflow completes with only partial advanced feature support.

FR-540 Cross-Reference Resolution Reporting

The system shall report whether supported cross references were resolved, preserved, degraded, or broken.

FR-541 Figure Identity Reporting

The system shall report whether figure numbering and figure identity remained coherent within supported workflows.

FR-542 Bibliography Ambiguity Reporting

The system shall report when bibliography or citation semantics cannot be safely preserved during import or comparison.

---

7.6 Template and Style Management

FR-601 Built-In Family Availability

The system shall provide three built-in document families named:

• article
• book
• website

FR-602 Family Metadata Disclosure

The system shall provide discoverable metadata for each available template/style family.

FR-603 Template Listing

The system shall provide a way to list available template families.

FR-604 Style Listing

The system shall provide a way to list available style families.

FR-605 Template Registration

The system shall allow registration of an additional document template.

FR-606 Style Registration

The system shall allow registration of an additional style definition.

FR-607 Paired Family Registration

The system shall allow registration of an additional template/style family association.

FR-608 Registration Validation

The system shall validate a proposed registration and report whether it is acceptable.

FR-609 Compatibility Declaration

The system shall associate each template/style family with declared capability metadata, including applicable document types and feature-level support.

FR-610 Family Resolution

The system shall resolve a family reference in a project to the corresponding registered template/style resources.

FR-611 Built-In Family Distinguishability

The system shall distinguish built-in families from additionally registered families in listing and inspection outputs.

FR-612 Family Conflict Reporting

The system shall report identifier conflicts or incompatible replacement attempts during registration.

FR-613 Family Capability Inspection

The system shall provide a way to inspect the declared capabilities of a family independently of any particular project.

FR-614 Registration Outcome Reporting

The system shall return a structured result for template, style, or family registration attempts, including success, warnings, and failure reasons.

FR-615 Family Selection Traceability

The system shall allow a project output or report to identify which family definition was actually resolved and used.

---

7.7 Validation and Drift Analysis

FR-701 Validation Invocation

The system shall allow validation of a project without performing a full build or import.

FR-702 Validation Scope

The system shall validate manifest integrity, referenced resources, selected feature level, and template/style compatibility.

FR-703 Build Preconditions Reporting

The system shall report whether a project is functionally ready for build.

FR-704 Drift Comparison

The system shall allow comparison of baseline and imported Markdown representations.

FR-705 Drift Classification

The system shall classify detected differences into at least the following functional categories:

• cosmetic
• normalized
• structural
• unsupported or ambiguous
• fatal

FR-706 Structural Drift Detection

The system shall identify structural changes affecting supported document semantics.

FR-707 Cross-Reference Integrity Check

The system shall detect and report broken or unresolved supported cross references.

FR-708 Figure Integrity Check

The system shall detect and report supported figure numbering or identity inconsistencies.

FR-709 Bibliography Integrity Check

The system shall detect and report unresolved bibliography or citation issues in supported workflows.

FR-710 Validation Result Output

The system shall produce validation and drift results in a machine-consumable form and a human-consumable form.

FR-711 Validation Severity Disclosure

The system shall distinguish blocking issues from warning-level issues in validation output.

FR-712 Comparison Input Disclosure

The system shall identify which document states or artifacts were compared during drift analysis.

FR-713 Drift Summary Reporting

The system shall provide a comparison summary in addition to detailed individual drift items.

FR-714 Drift Source Association

Where source mapping is available, the system shall associate drift findings with relevant source files, sections, or tracked boundaries.

FR-715 Ambiguity Classification

The system shall classify ambiguity findings distinctly from confirmed structural defects where the distinction is meaningful.

FR-716 Validation-Comparison Linkage

The system shall support associating comparison outcomes with the validation and build/import states that produced them.

---

7.8 CLI Functions

FR-801 Local CLI Availability

The system shall provide a local command-line interface for core markidocx functions.

FR-802 CLI Build Command

The CLI shall provide a command to build/export a project.

FR-803 CLI Import Command

The CLI shall provide a command to import DOCX content into project-compatible Markdown outputs.

FR-804 CLI Validate Command

The CLI shall provide a command to validate a project.

FR-805 CLI Diff Command

The CLI shall provide a command to compare round-trip outputs or equivalent document states.

FR-806 CLI Inspect Command

The CLI shall provide a command to inspect resolved project information.

FR-807 CLI Template Listing Command

The CLI shall provide a command to list template families.

FR-808 CLI Style Listing Command

The CLI shall provide a command to list styles or style families.

FR-809 CLI Registration Commands

The CLI shall provide commands to register templates, styles, or families.

FR-810 CLI Test Command

The CLI shall provide a command to execute the defined test suite or end-to-end validation workflow.

FR-811 CLI Exit Status Behavior

The CLI shall return success, warning, or failure outcomes through distinguishable exit behavior and output.

FR-812 CLI Structured Output

The CLI shall support a structured output mode for machine consumption.

FR-813 CLI Workflow Invocation

The CLI shall provide a way to invoke supported composite workflows where such workflows are exposed by the system.

FR-814 CLI Evidence Retrieval

The CLI shall provide a way to retrieve or emit available reports and evidence artifacts for relevant operations.

FR-815 CLI Capability Disclosure Command

The CLI shall provide a command to retrieve system or project capability information.

FR-816 CLI Health and Version Commands

The CLI shall provide a way to retrieve operational health and version information where applicable to the local or connected execution context.

FR-817 CLI Fallback Visibility

The CLI shall visibly distinguish fallback and partial-result outputs from fully successful outputs.

---

7.9 REST Service Functions

FR-901 REST Service Availability

The system shall provide a REST-accessible service exposing core markidocx functions.

FR-902 REST Project Validation

The service shall allow clients to submit a project for validation and receive a structured result.

FR-903 REST Build

The service shall allow clients to request document build/export and retrieve resulting artifacts and reports.

FR-904 REST Import

The service shall allow clients to submit DOCX content for import and receive generated Markdown-compatible outputs and reports.

FR-905 REST Drift Comparison

The service shall allow clients to request drift analysis between supplied or project-associated document states.

FR-906 REST Template Listing

The service shall provide an endpoint for listing available template families.

FR-907 REST Style Listing

The service shall provide an endpoint for listing available styles or style families.

FR-908 REST Registration

The service shall allow submission of additional template/style registrations and return validation results.

FR-909 REST Capability Inspection

The service shall provide a way to retrieve supported capability and feature-level information.

FR-910 REST Health Disclosure

The service shall provide a machine-readable health/status response.

FR-911 REST Version Disclosure

The service shall provide a machine-readable version response.

FR-912 REST Structured Responses

The service shall return structured responses that identify status, outputs, warnings, and errors.

FR-913 REST Workflow Invocation

The service shall provide a way to invoke supported composite workflows through REST.

FR-914 REST Evidence Access

The service shall provide access to reports and evidence artifacts produced by relevant operations.

FR-915 REST Operation Context Disclosure

The service shall identify the project, family, feature level, and workflow context relevant to a response where applicable.

FR-916 REST Fallback and Partial Status Disclosure

The service shall explicitly disclose fallback and partial-result conditions in structured responses.

---

7.10 MCP Functions

FR-1001 MCP Availability

The system shall provide an MCP-compatible interface exposing markidocx capabilities to agentic clients.

FR-1002 MCP Template Discovery

The MCP interface shall expose a tool or equivalent operation to list available template families.

FR-1003 MCP Style Discovery

The MCP interface shall expose a tool or equivalent operation to list available style families.

FR-1004 MCP Project Validation

The MCP interface shall expose a tool or equivalent operation to validate a project.

FR-1005 MCP Project Inspection

The MCP interface shall expose a tool or equivalent operation to inspect a project.

FR-1006 MCP Build

The MCP interface shall expose a tool or equivalent operation to build/export a project.

FR-1007 MCP Import

The MCP interface shall expose a tool or equivalent operation to import DOCX content.

FR-1008 MCP Drift Comparison

The MCP interface shall expose a tool or equivalent operation to compare round-trip states.

FR-1009 MCP Test Execution

The MCP interface shall expose a tool or equivalent operation to run end-to-end tests.

FR-1010 MCP Version Disclosure

The MCP interface shall expose a tool or equivalent operation to disclose system version information.

FR-1011 MCP Resource Exposure

The MCP interface shall expose relevant machine-consumable resources for manifests, capabilities, template metadata, style metadata, and current documentation corpus metadata.

FR-1012 MCP Workflow Invocation

The MCP interface shall expose supported composite workflow functions to agentic clients.

FR-1013 MCP Evidence Retrieval

The MCP interface shall expose a way to retrieve reports and evidence artifacts relevant to completed operations.

FR-1014 MCP Capability Context

The MCP interface shall expose enough metadata for a client to determine whether a project, family, or workflow is compatible before invocation.

FR-1015 MCP Fallback Visibility

The MCP interface shall explicitly surface fallback, ambiguity, degradation, and partial-result conditions in tool outputs or resources.

---

7.11 Test and Regression Functions

FR-1101 Stable Documentation Corpus

The system shall maintain the latest stable markidocx documentation as a managed documentation project.

FR-1102 Documentation-Based E2E Testing

The system shall support execution of end-to-end validation using the latest stable markidocx documentation as the test corpus.

FR-1103 Round-Trip Regression Execution

The system shall support a test flow in which the documentation corpus is built, exported, imported, and compared.

FR-1104 Template Coverage in E2E Testing

The system shall support end-to-end testing against the built-in article, book, and website families where applicable.

FR-1105 Feature-Level Coverage in E2E Testing

The system shall support execution of tests covering LEVEL1 and LEVEL3 behavior as represented in the stable documentation corpus.

FR-1106 Test Result Reporting

The system shall provide a report identifying whether regression and end-to-end validation passed, warned, or failed.

FR-1107 Release Evidence Support

The system shall support generation or assembly of evidence derived from end-to-end validation runs.

FR-1108 Regression Workflow Status Disclosure

The system shall disclose which steps of a regression workflow completed, warned, failed, or fell back.

FR-1109 Documentation Corpus Identity Disclosure

The system shall disclose which stable documentation corpus version or identity was used for a regression run.

FR-1110 Regression Artifact Traceability

The system shall allow regression outputs, reports, and evidence to be associated with the corresponding test run.

---

7.12 Error and Warning Behavior

FR-1201 Explicit Failure Reporting

The system shall explicitly report functional failures rather than silently omitting failed operations.

FR-1202 Explicit Warning Reporting

The system shall explicitly report warnings when an operation completes with ambiguity, normalization, unsupported constructs, or partial degradation.

FR-1203 Unsupported Construct Visibility

The system shall surface unsupported or ambiguous constructs in import, export, validation, or diff results.

FR-1204 Partial Result Disclosure

When an operation produces partial results, the system shall indicate the partial nature of those results.

FR-1205 Non-Silent Degradation

The system shall not silently discard known document constructs that fall outside supported round-trip behavior.

FR-1206 Ambiguity Reporting

The system shall explicitly distinguish ambiguous outcomes from confirmed successful preservation when the distinction is meaningful.

FR-1207 Fallback Reporting

The system shall explicitly report when a workflow falls back from its preferred processing path to a degraded but usable path.

FR-1208 Severity Visibility

The system shall make severity or functional significance visible in warnings and failures.

FR-1209 Reason Disclosure

The system shall provide a reason or classification for failures, warnings, fallback states, and ambiguities.

FR-1210 Output State Identification

The system shall identify whether a returned output is final, partial, fallback, degraded, or unresolved.

---

7.13 Composite Workflow Functions

FR-1301 Single-File Round-Trip Workflow

The system shall support a composite workflow that validates, builds, imports, and compares a single-file project.

FR-1302 Multi-File Round-Trip Workflow

The system shall support a composite workflow that inspects, validates, builds, imports, redistributes or falls back, and compares a multi-file project.

FR-1303 Composite Workflow Result Reporting

The system shall return a structured result for a composite workflow that includes the statuses and outputs of its constituent steps.

FR-1304 Composite Workflow Step Visibility

The system shall disclose which constituent steps were executed in a composite workflow.

FR-1305 Composite Workflow Fallback Visibility

The system shall disclose whether a composite workflow completed fully, completed with fallback, completed partially, or failed.

FR-1306 Release Regression Workflow

The system shall support a composite workflow that performs end-to-end regression on the latest stable documentation corpus.

FR-1307 Family-Switch Build Workflow

The system shall support a workflow in which the same project is built under more than one compatible family and the results are separately reported.

FR-1308 Workflow Reusability Across Interfaces

Where a composite workflow is supported, the system shall expose it consistently through the relevant supported interfaces.

FR-1309 Workflow Context Identity

The system shall provide identity information for a composite workflow execution sufficient to associate its outputs and evidence.

FR-1310 Workflow Output Aggregation

The system shall aggregate build, import, validation, comparison, and related outputs into a coherent workflow result where those operations are part of the invoked workflow.

---

7.14 Evidence and Report Management

FR-1401 Validation Report Availability

The system shall make validation results available as reusable reports.

FR-1402 Build Report Availability

The system shall make build results available as reusable reports.

FR-1403 Import Report Availability

The system shall make import results available as reusable reports.

FR-1404 Drift Report Availability

The system shall make comparison and drift results available as reusable reports.

FR-1405 Warning and Ambiguity Report Availability

The system shall make warnings, ambiguities, degradations, and fallback conditions reviewable as structured report content.

FR-1406 Release Evidence Assembly

The system shall support assembly of a coherent release evidence set from relevant validation, build, import, comparison, and regression outputs.

FR-1407 Evidence Composition Disclosure

The system shall identify which reports, artifacts, and operation results are included in an evidence set.

FR-1408 Evidence Status Summary

The system shall provide a summary of success, warnings, fallback conditions, partial results, and failures across an evidence set.

FR-1409 Evidence Retrieval Across Interfaces

The system shall allow reports and evidence artifacts to be retrieved through supported interfaces where those interfaces expose the originating operations.

FR-1410 Evidence Traceability

The system shall support associating reports and evidence with the project, family, feature level, workflow, and run context that produced them.

FR-1411 Report Human Readability

The system shall provide report output in a form suitable for human inspection.

FR-1412 Report Machine Readability

The system shall provide report output in a machine-consumable form.

FR-1413 Report Completeness Disclosure

The system shall disclose when a report or evidence set is incomplete.

FR-1414 Release Decision Support Visibility

The system shall make it possible to determine from evidence outputs whether a release-time workflow completed cleanly, completed with warnings, or failed.

---

8. Functional Use Cases

UC-01 Single-File Round-Trip

A user provides a single Markdown project, builds DOCX, edits the DOCX, imports it back, and receives an updated Markdown result plus drift report.

UC-02 Multi-File Review Workflow

A user provides a multi-file project, exports one DOCX for review, imports the reviewed DOCX, and receives redistributed or merged Markdown outputs with section mapping status.

UC-03 Template Switching

A user builds the same content using article, book, and website families and receives corresponding output artifacts without changing the source content.

UC-04 Validation Before Build

A user validates a project and receives confirmation of readiness or a list of blocking issues.

UC-05 External Automation

An external system submits a project to the REST service for build, import, or comparison and receives structured results.

UC-06 Agentic Interaction

An MCP client discovers available templates, validates a project, triggers a build, and retrieves validation outcomes.

UC-07 Product Self-Test

A release process runs end-to-end tests against the latest stable markidocx documentation and records regression status.

UC-08 Warning and Ambiguity Review

A user inspects warnings, degradations, ambiguities, fallback conditions, and related report details before deciding whether and how to apply results.

UC-09 Release Evidence Review

A release manager or equivalent actor reviews assembled validation, build, import, and comparison evidence for a release decision.

UC-10 Composite Workflow Invocation

A user or client invokes a full round-trip or regression workflow as one meaningful system operation and receives a combined result.

---

9. Functional Constraints

FC-01 Supported Semantic Envelope

The system shall only claim preservation for constructs within the declared supported feature levels and managed workflow boundaries.

FC-02 Project-Scoped Operation

Build, import, validation, and drift functions shall operate in relation to an explicit project context or explicitly supplied artifact set.

FC-03 Family-Scoped Capability

Template/style application shall be constrained by the declared capabilities of the selected family.

FC-04 Fallback Disclosure

Whenever the system falls back from source-aligned redistribution to merged or degraded output, it shall disclose that fallback.

FC-05 Composite Workflow Transparency

Composite workflows shall not obscure the outcomes of their constituent functional steps.

FC-06 Evidence Traceability

Evidence and reports shall remain attributable to their originating operation or workflow context.

---

10. Acceptance-Oriented Functional Summary

markidocx shall be considered functionally conformant to this FRS when it can, at minimum:

1. accept and validate a project manifest
2. compose single-file and multi-file Markdown documents
3. export DOCX using built-in document families
4. import edited DOCX back into Markdown-compatible outputs
5. support all declared LEVEL1 functions
6. support declared LEVEL3 functions for managed cases
7. detect and classify round-trip drift
8. expose core functions through CLI
9. expose core functions through REST
10. expose core functions through MCP
11. register additional templates and styles
12. run end-to-end tests using the latest stable markidocx documentation corpus
13. expose fallback, ambiguity, and partial-result states explicitly
14. support composite workflow invocation for meaningful round-trip scenarios
15. produce reusable reports and release evidence artifacts

---

11. Related Artifacts

This FRS is expected to relate to:

• PRD: markidocx
• UCC: markidocx
• Non-Functional Requirements document
• API/interface contracts
• schema definitions for manifests and registrations
• test specifications
• acceptance criteria catalog
• system design specification
• architecture decision records

---

12. Appendix: Suggested Requirement Trace Anchors

A minimal traceability map should connect:

• PRD product goals → FRS requirement groups
• UCC use cases → FRS requirement IDs
• FRS requirement IDs → interface contracts
• FRS requirement IDs → acceptance tests
• FRS requirement Iression scenarios

Example trace anchors:

• PRD Round-Trip Editing → FR-201 to FR-308, FR-1301 to FR-1305
• PRD Multi-File Composition → FR-401 to FR-412, FR-1302
• PRD Built-In Families → FR-601 to FR-615
• PRD CLI/REST/MCP accessibility → FR-801 to FR-1015
• PRD E2E documentation corpus → FR-1101 to FR-1110
• UCC Warning and ambiguity review → FR-1202 to FR-1210, FR-1405
• UCC Release evidence review → FR-1406 to FR-1414
• UCC Composite workflow invocation → FR-1301 to FR-1310

---

13. Appendix: UCC to FRS Traceability Matrix

Project and Manifest

• UC-001 Define document project ↔ FR-101 to FR-110
• UC-002 Inspect project configuration ↔ FR-104 to FR-110
• UC-003 Validate project readiness ↔ FR-701 to FR-703, FR-711

Build and Export

• UC-004 Build DOCX review artifact ↔ FR-201 to FR-214
• UC-005 Build using alternate family ↔ FR-204 to FR-205, FR-210 to FR-212, FR-603 to FR-615

Import and Round-Trip

• UC-006 Import edited DOCX into Markdown ↔ FR-301 to FR-314 *d-trip single-file document ↔ FR-201 to FR-308, FR-704 to FR-716, FR-1301 to FR-1305
• UC-008 Round-trip multi-file document ↔ FR-401 to FR-412, FR-704 to FR-716, FR-1302 to FR-1305
• UC-009 Redistribute imported edits to source files ↔ FR-404 to FR-412
• UC-010 Fallback to merged Markdown import ↔ FR-406, FR-412, FR-1207, FR-1210
• UC-011 Detect round-trip drift ↔ FR-704 to FR-716
• UC-022 Review warning and ambiguity report ↔ FR-1202 to FR-1210, FR-1405, FR-1411 to FR-1412

Feature Levels

ld LEVEL1 document ↔ FR-501 to FR-508

• UC-015 Build LEVEL3 document ↔ FR-531 to FR-542
• UC-016 Generate automatic diagrams ↔ FR-533 to FR-534, FR-538
• UC-017 Process bibliography-aware document ↔ FR-535 to FR-536, FR-542

Interfaces

• UC-018 Execute local CLI workflow ↔ FR-801 to FR-817
• UC-019 Execute REST-based workflow ↔ FR-901 to FR-916
• UC-020 Execute MCP-based workflow ↔ FR-1001 to FR-1015
• UC-023 Retrieve system capability metadata ↔ FR-105, FR-537, FR-613, FR-815, FR-909, FR-1011, FR-1014
• UC-024 Retrieve health and version status ↔ FR-816, FR-910 to FR-911, FR-1010

Release and Testing

• UC-021 Run end-to-end regression on stable docs ↔ FR-1101 to FR-1110, FR-1306
• UC-025 Build and inspect release evidence ↔ FR-1107 to FR-1110, FR-1401 to FR-1414

---

14. Concise Revision Summary

This revision preserves the prior FRS and extends it in four main ways:

• it adds composite workflow requirements
• it adds evidence and report management requirements
• it thens fallback, ambiguity, and partial-result handling
• it improves traceability to the UCC

That makes the FRS better aligned with the richer actor-goal structure without changing the original product intent.