generated from coulomb/repo-seed
tegwick
c6dfc9b172
- 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>
1192 lines
41 KiB
Markdown
1192 lines
41 KiB
Markdown
# 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.
|
||
|