marki-docx/specs/MarkiDocxUseCaseCatalog_v0.1.md

UCC

Use Case Catalog

Use Case Catalog: markidocx

System Scope: markidocx Artifact Type: Use Case Catalog Purpose: Structured catalog of actor-goal-centered use cases for the markidocx round-trip editing system Status: Draft Version: 1.0 Parent Artifacts: PRD markidocx, FRS markidocx

---

1. Definition

This Use Case Catalog defines the externally observable functional behavior of markidocx from the perspective of its actors.

markidocx enables controlled Markdown ↔ DOCX round-trip editing with support for:

• local CLI usage
• REST-based service interaction
• MCP-based agent interaction
• template/style-driven document generation
• multi-file composition
• feature-level processing
• validation and drift detection
• end-to-end regression based on the latest stable markidocx documentation corpus

This catalog organizes the major actor goals that the system must support and provides structured use case descriptions suitable for traceability into the FRS and acceptance artifacts.

---

2. Context

markidocx sits between structured Markdown authoring and Word-centric editorial collaboration.

Its main functional challenge is not simple format conversion, but managed round-trip behavior under defined semantic constraints.

The catalog therefore focuses on use cases where actors need to:

• define a document project
• inspect and validate project readiness
• build review artifacts
• import edited DOCX files back into Markdown
• preserve or recover structure in multi-file projects
• apply template/style families
• detect drift
• automate workflows through service interfaces
• access the system through agentic tooling

This UCC is positioned between product goals and detailed functional requirements.

---

3. Actor Model

3.1 Primary Actors

A-01 Document Author

A person maintaining canonical Markdown sources and preparing documents for export, review, and re-import.

A-02 Technical Editor

A person responsible for document quality, structure, and consistency across editing cycles.

A-03 Reviewer

A stakeholder who edits or comments on generated DOCX artifacts, usually without direct interaction with Markdown sources.

A-04 Build Operator

A person or automation operator invoking builds, validations, or regression flows locally or in controlled environments.

A-05 Integration Client

An external system calling the REST interface to validate, build, import, compare, or register artifacts.

A-06 MCP Client

An agentic tool using the MCP interface to inspect projects, trigger operations, and retrieve results.

A-07 Template Administrator

A person responsible for registering, updating, or governing templates and styles.

A-08 Release Manager

A person or automation responsible for release validation using the stable documentation corpus as end-to-end testcase.

---

3.2 Supporting Actors

SA-01 Template Registry

Logical externalized registry of available built-in and registered template/style families.

SA-02 Diagram Renderer

A rendering toolchain used for automatic diagrams in LEVEL3 workflows.

SA-03 Bibliography Processor

A citation/bibliography-capable processor used in bibliography-aware workflows.

SA-04 File System / Artifact Store

A storage context for source bundles, generated artifacts, imports, and reports.

SA-05 Source Mapping Context

A project-specific mapping context allowing re-association of imported content to original source boundaries.

---

4. Use Case Levels

The catalog uses three abstraction levels:

• Summary – broad actor goals spanning multiple interactions
• User-goal – complete actor goals that produce meaningful results
• Subfunction – reusable lower-level interactions supporting user goals

The primary catalog emphasis is on user-goal use cases.

---

5. Catalog Index

ID	Name	Level	Primary Actor	Goal
UC-001	Define document project	User-goal	Document Author	Declare a document project usable by markidocx
UC-002	Inspect project configuration	User-goal	Document Author	Understand the resolved structure and capabilities of a project
UC-003	Validate project readiness	User-goal	Build Operator	Determine whether a project is functionally ready
UC-004	Build DOCX review artifact	User-goal	Document Author	Produce a DOCX artifact from Markdown sources
UC-005	Build using alternate family	User-goal	Technical Editor	Export the same source using article, book, or website family
UC-006	Import edited DOCX into Markdown	User-goal	Document Author	Re-import reviewed DOCX content into Markdown-compatible form
UC-007	Round-trip single-file document	Summary	Document Author	Complete a full single-file Markdown → DOCX → Markdown cycle
UC-008	Round-trip multi-file document	Summary	Technical Editor	Complete a full multi-file round-trip cycle with source-aware handling
UC-009	Redistribute imported edits to source files	User-goal	Technical Editor	Re-associate imported content with original source files
UC-010	Fallback to merged Markdown import	User-goal	Technical Editor	Recover usable Markdown when source redistribution is ambiguous
UC-011	Detect round-trip drift	User-goal	Technical Editor	Compare baseline and imported content for semantic drift
UC-012	List available families	User-goal	Template Administrator	Discover built-in and registered template/style families
UC-013	Register additional template family	User-goal	Template Administrator	Add a new template/style family to the system
UC-014	Build LEVEL1 document	User-goal	Document Author	Produce and round-trip a document using LEVEL1 features
UC-015	Build LEVEL3 document	User-goal	Technical Editor	Produce and round-trip a document using LEVEL3 features
UC-016	Generate automatic diagrams	Subfunction	Document Author	Include rendered diagrams derived from source declarations
UC-017	Process bibliography-aware document	Subfunction	Technical Editor	Include citations and bibliography during build/import workflows
UC-018	Execute local CLI workflow	Summary	Build Operator	Perform markidocx operations through the CLI
UC-019	Execute REST-based workflow	Summary	Integration Client	Perform markidocx operations through the REST service
UC-020	Execute MCP-based workflow	Summary	MCP Client	Perform markidocx operations through MCP tools
UC-021	Run end-to-end regression on stable docs	User-goal	Release Manager	Validate latest stable markidocx documentation as canonical testcase
UC-022	Review warning and ambiguity report	User-goal	Technical Editor	Inspect unsupported, degraded, or ambiguous outcomes
UC-023	Retrieve system capability metadata	User-goal	Integration Client	Discover supported feature levels and interfaces
UC-024	Retrieve health and version status	User-goal	Build Operator	Determine operational availability and version state
UC-025	Build and inspect release evidence	User-goal	Release Manager	Produce auditable build/import/diff evidence for a release

---

6. Cross-Reference Map

• UC-007 Round-trip single-file document includes UC-003, UC-004, UC-006, UC-011
• UC-008 Round-trip multi-file document includes UC-002, UC-003, UC-004, UC-006, UC-009 or UC-010, UC-011
• UC-015 Build LEVEL3 document includes UC-016 and UC-017 where applicable
• UC-018 Execute local CLI workflow varies UC-003, UC-004, UC-006, UC-011, UC-012, UC-013, UC-021
• UC-019 Execute REST-based workflow varies UC-003, UC-004, UC-006, UC-011, UC-023, UC-024
• UC-020 Execute MCP-based workflow varies UC-002, UC-003, UC-004, UC-006, UC-011, UC-023

---

7. Detailed Use Cases

---

UC-001 Define document project

Level: User-goal Primary Actor: Document Author Supporting Actors: File System / Artifact Store Goal: Create a valid project definition that markidocx can process

Preconditions

• The actor has a set of Markdown sources or intends to create one
• The actor knows the intended document type and feature level
• Required source files are accessible

Guarantees

Success

• A project definition exists
• The project declares source files, feature level, and selected family references
• The project can be submitted for inspection or validation

Minimal

• No existing project data is modified unintentionally

Main Success Scenario

1. The actor provides a project definition for a document set.
2. The system reads the provided manifest content.
3. The system recognizes declared sources, feature level, and family references.
4. The system acknowledges the project as a recognizable markidocx project.
5. The actor can proceed with inspection or validation.

Extensions

• 3a. A referenced source is missing. The system reports the missing resource.
• 3b. The manifest contains unsupported settings. The system reports invalid or unsupported configuration.
• 4a. Template or style references cannot be resolved. The system reports unresolved family references.

Special Requirements

• The use case must remain independent of interface channel
• The project definition must be reusable across CLI, REST, and MCP workflows

---

UC-002 Inspect project configuration

Level: User-goal Primary Actor: Document Author Goal: View the resolved structure and effective capabilities of a project

Preconditions

• A recognizable project definition exists

Guarantees

Success

• The actor receives a resolved view of project structure
• The actor can see source ordering, family selection, and effective feature level

Minimal

• The project remains unchanged

Main Success Scenario

1. The actor requests inspection of a project.
2. The system resolves the project definition.
3. The system determines the effective source ordering.
4. The system determines selected family and declared capability level.
5. The system returns inspection output to the actor.

Extensions

• 2a. The project cannot be resolved. The system reports why inspection cannot proceed.
• 4a. Registered family metadata is incomplete. The system reports incomplete capability resolution.

Related Use Cases

• UC-003 Validate project readiness
• UC-008 Round-trip multi-file document

---

UC-003 Validate project readiness

Level: User-goal Primary Actor: Build Operator Goal: Determine whether a project is functionally ready for processing

Preconditions

• A project definition exists

Guarantees

Success

• The actor receives a validation result
• Blocking and non-blocking issues are distinguished
• Functional readiness is made explicit

Minimal

• The project remains unchanged

Main Success Scenario

1. The actor submits a project for validation.
2. The system checks manifest consistency.
3. The system checks referenced resources.
4. The system checks feature-level and family compatibility.
5. The system determines readiness status.
6. The system returns validation output.

Extensions

• 2a. The manifest is malformed. The system reports validation failure.
• 3a. A required resource is unavailable. The system reports a blocking issue.
• 4a. The selected family does not support the declared feature level. The system returns a compatibility failure.
• 5a. Non-blocking issues exist. The system returns a warning state rather than outright failure.

Related Use Cases

• UC-004 Build DOCX review artifact
• UC-021 Run end-to-end regression on stable docs

---

UC-004 Build DOCX review artifact

Level: User-goal Primary Actor: Document Author Supporting Actors: Template Registry, File System / Artifact Store Goal: Generate a DOCX artifact from the project’s Markdown sources

Preconditions

• The project is valid or sufficiently processable
• The selected template family is available

Guarantees

Success

• A DOCX artifact is generated
• Declared project content is included according to supported features
• Build status and artifact metadata are returned

Minimal

• No existing canonical Markdown source is altered

Main Success Scenario

1. The actor requests a DOCX build for a project.
2. The system resolves the project structure.
3. The system composes the Markdown sources.
4. The system resolves the selected template/style family.
5. The system applies supported processing for the declared feature level.
6. The system generates a DOCX artifact.
7. The system returns the artifact reference and build report.

Extensions

• 2a. The project cannot be resolved. The system reports a build failure.
• 4a. The selected family is unavailable. The system reports an unresolved family reference.
• 5a. A supported asset cannot be resolved. The system returns a warning or failure depending on severity.
• 6a. Build output is generated with degradations. The system returns the artifact with warnings.

Related Use Cases

• UC-005 Build using alternate family
• UC-014 Build LEVEL1 document
• UC-015 Build LEVEL3 document

---

UC-005 Build using alternate family

Level: User-goal Primary Actor: Technical Editor Goal: Build the same source content using a different built-in or registered family

Preconditions

• A project definition exists
• More than one compatible family is available or known

Guarantees

Success

• The actor receives an output artifact built using the selected alternate family
• Canonical content remains unchanged

Minimal

• No incompatible family is silently applied

Main Success Scenario

1. The actor chooses an alternate family for the build.
2. The system resolves the requested family.
3. The system checks capability compatibility.
4. The system builds the document using the selected family.
5. The system returns the resulting artifact and build report.

Extensions

• 2a. The requested family is unknown. The system reports the family cannot be resolved.
• 3a. The requested family is incompatible with the project’s feature level. The system returns a compatibility failure.

Related Use Cases

• UC-012 List available families
• UC-013 Register additional template family

---

UC-006 Import edited DOCX into Markdown

Level: User-goal Primary Actor: Document Author Supporting Actors: Source Mapping Context, File System / Artifact Store Goal: Import an edited DOCX into Markdown-compatible output

Preconditions

• A DOCX document exists for import
• If source-aware import is expected, a project context exists

Guarantees

Success

• The system produces Markdown-compatible import output
• Supported structure is preserved
• Import warnings and ambiguities are disclosed

Minimal

• Existing source content remains unchanged unless the actor deliberately applies imported output later

Main Success Scenario

1. The actor submits a DOCX file for import.
2. The system recognizes the import request context.
3. The system extracts supported document content.
4. The system maps recognized content into Markdown-compatible representation.
5. The system applies project-aware or source-aware mapping when available.
6. The system produces import output and reports.
7. The actor receives the output and related warnings or mapping status.

Extensions

• 2a. No project context is provided. The system produces a valid import result without project-aware redistribution.
• 3a. The DOCX contains unsupported constructs. The system reports unsupported constructs explicitly.
• 5a. Source mapping is ambiguous. The system reports ambiguity and may fall back to merged output.
• 6a. Import completes with degradations. The system returns output plus warning classification.

Related Use Cases

• UC-009 Redistribute imported edits to source files
• UC-010 Fallback to merged Markdown import
• UC-022 Review warning and ambiguity report

---

UC-007 Round-trip single-file document

Level: Summary Primary Actor: Document Author Goal: Complete a full single-file round-trip editing cycle

Preconditions

• A valid single-file project exists

Guarantees

Success

• A DOCX review artifact is built
• The edited DOCX is imported back
• Semantic drift is reported

Minimal

• Canonical source remains recoverable

Main Success Scenario

1. The actor validates the single-file project.
2. The actor builds a DOCX artifact.
3. A reviewer edits the DOCX.
4. The actor imports the edited DOCX.
5. The actor compares baseline and imported Markdown.
6. The system returns a drift report.
7. The actor decides how to apply imported changes.

Includes

• UC-003 Validate project readiness
• UC-004 Build DOCX review artifact
• UC-006 Import edited DOCX into Markdown
• UC-011 Detect round-trip drift

Extensions

• 4a. Import contains unsupported constructs. The system provides import output with explicit warnings.
• 5a. Structural drift is detected. The system highlights drift classification.

---

UC-008 Round-trip multi-file document

Level: Summary Primary Actor: Technical Editor Goal: Complete a round-trip cycle for a multi-file project while preserving source structure where possible

Preconditions

• A valid multi-file project exists
• Source mapping or section-origin context is available

Guarantees

Success

• A single review artifact is built from multiple sources
• Imported changes are either redistributed or clearly surfaced in fallback form
• Drift is reported with source-awareness where possible

Minimal

• Source structure is not silently lost

Main Success Scenario

1. The actor inspects the multi-file project.
2. The actor validates the project.
3. The actor builds a single DOCX review artifact.
4. A reviewer edits the DOCX.
5. The actor imports the edited DOCX into the project context.
6. The system attempts source-aware redistribution.
7. The system either redistributes content or provides a managed fallback.
8. The actor runs drift comparison.
9. The system returns redistribution status and drift results.

Includes

• UC-002 Inspect project configuration
• UC-003 Validate project readiness
• UC-004 Build DOCX review artifact
• UC-006 Import edited DOCX into Markdown
• UC-009 Redistribute imported edits to source files or UC-010 Fallback to merged Markdown import
• UC-011 Detect round-trip drift

Extensions

• 6a. Redistribution is ambiguous. The system falls back to merged output and reports the condition.
• 8a. Drift affects section boundaries or identifiers. The system returns structural warnings.

---

UC-009 Redistribute imported edits to source files

Level: User-goal Primary Actor: Technical Editor Supporting Actors: Source Mapping Context Goal: Place imported content back into source-aligned Markdown outputs

Preconditions

• A project-aware import result exists
• Source-origin metadata or equivalent mapping context exists

Guarantees

Success

• Imported content is redistributed into source-aligned outputs
• Redistribution status is reported

Minimal

• The system does not silently assign ambiguous content to incorrect sources

Main Success Scenario

1. The actor requests source-aware redistribution of imported content.
2. The system loads source-origin mapping information.
3. The system associates imported sections with original source boundaries.
4. The system produces source-aligned Markdown outputs.
5. The system reports redistribution success and any warnings.

Extensions

• 2a. Required mapping information is missing. The system reports redistribution cannot proceed safely.
• 3a. An imported section matches multiple possible source boundaries. The system flags the ambiguity.
• 4a. Redistribution is only partially successful. The system produces partial output and explicit warnings.

Related Use Cases

• UC-010 Fallback to merged Markdown import

---

UC-010 Fallback to merged Markdown import

Level: User-goal Primary Actor: Technical Editor Goal: Recover a usable Markdown result when source redistribution cannot be completed safely

Preconditions

• An import result exists
• Safe redistribution is unavailable or ambiguous

Guarantees

Success

• A merged Markdown output is available
• The fallback condition is explicitly disclosed

Minimal

• Imported content is not lost

Main Success Scenario

1. The system detects that source redistribution cannot be completed safely.
2. The system prepares a merged Markdown representation.
3. The system marks the result as fallback output.
4. The actor receives the merged Markdown and mapping warnings.

Extensions

• 2a. Import output itself is degraded. The system returns fallback output with additional warning classification.

---

UC-011 Detect round-trip drift

Level: User-goal Primary Actor: Technical Editor Goal: Compare original and imported document states and classify their differences

Preconditions

• A baseline document state and an imported or alternate state exist

Guarantees

Success

• The actor receives a drift report
• Differences are classified into meaningful categories
• Structural changes are distinguished from cosmetic normalization

Minimal

• No compared content is modified

Main Success Scenario

1. The actor requests drift comparison.
2. The system loads the baseline and comparison states.
3. The system compares the two states.
4. The system classifies detected differences.
5. The system reports comparison status and classified differences.

Extensions

• 2a. One of the compared states is unavailable. The system reports comparison cannot proceed.
• 4a. Broken references or citation issues are detected. The system classifies them as structural or unresolved problems.

Related Use Cases

• UC-022 Review warning and ambiguity report

---

UC-012 List available families

Level: User-goal Primary Actor: Template Administrator Goal: Discover built-in and registered families

Preconditions

• The system is operational

Guarantees

Success

• The actor receives a list of available families
• Built-in and registered families are visible with metadata

Minimal

• Registry state remains unchanged

Main Success Scenario

1. The actor requests the family list.
2. The system retrieves available family registrations.
3. The system returns family identifiers and metadata summary.

Extensions

• 2a. Registry information is unavailable. The system reports inability to provide the list.

---

UC-013 Register additional template family

Level: User-goal Primary Actor: Template Administrator Supporting Actors: Template Registry Goal: Add a new template/style family to the system

Preconditions

• The actor has a candidate family definition and associated resources

Guarantees

Success

• The system accepts and registers the new family
• The family becomes discoverable for future use

Minimal

• Invalid registrations are not partially accepted without disclosure

Main Success Scenario

1. The actor submits a new family registration.
2. The system validates the family definition and referenced resources.
3. The system checks compatibility declarations.
4. The system stores or activates the registration.
5. The system confirms successful registration.

Extensions

• 2a. The family definition is invalid. The system rejects the registration with reasons.
• 3a. Declared capabilities are inconsistent. The system reports a validation error.
• 4a. The family conflicts with an existing identifier. The system reports a registration conflict.

---

UC-014 Build LEVEL1 document

Level: User-goal Primary Actor: Document Author Goal: Process a document using LEVEL1 features

Preconditions

• The project declares LEVEL1 or compatible capability
• The selected family supports LEVEL1

Guarantees

Success

• The document is processed with support for headings, lists, tables, footnotes, images, and links

Minimal

• Unsupported non-LEVEL1 constructs are surfaced rather than silently accepted

Main Success Scenario

1. The actor requests build or round-trip processing for a LEVEL1 project.
2. The system recognizes the declared feature level.
3. The system applies LEVEL1 support rules.
4. The system returns the resulting artifacts and/or reports.

Extensions

• 2a. The selected family does not support LEVEL1. The system reports incompatibility.
• 3a. Unsupported constructs are encountered. The system reports warnings or failures as appropriate.

---

UC-015 Build LEVEL3 document

Level: User-goal Primary Actor: Technical Editor Goal: Process a document using LEVEL3 features

Preconditions

• The project declares LEVEL3
• The selected family supports LEVEL3-related behaviors
• Supporting processors are available where needed

Guarantees

Success

• The document is processed with support for cross references, numbered figures, diagrams, and bibliography-aware workflows

Minimal

• Unsupported advanced features are surfaced explicitly

Main Success Scenario

1. The actor requests build or round-trip processing for a LEVEL3 project.
2. The system recognizes the declared feature level.
3. The system resolves required supporting processors.
4. The system applies LEVEL3 support rules.
5. The system returns artifacts and reports.

Includes

• UC-016 Generate automatic diagrams
• UC-017 Process bibliography-aware document

Extensions

• 3a. Required supporting processors are unavailable. The system reports inability to complete full LEVEL3 processing.
• 4a. Cross references or citations cannot be resolved safely. The system reports unresolved advanced constructs.

---

UC-016 Generate automatic diagrams

Level: Subfunction Primary Actor: Document Author Supporting Actors: Diagram Renderer Goal: Include rendered diagrams derived from source declarations

Preconditions

• The project includes diagram source declarations
• Diagram rendering capability is available

Guarantees

Success

• Diagram output is included in generated artifacts
• Diagram intent remains linked to its source representation within the managed workflow

Minimal

• Missing diagram support is explicitly reported

Main Success Scenario

1. The system encounters a diagram source declaration during processing.
2. The system invokes diagram-capable processing.
3. The system includes the resulting rendered diagram in build output.
4. The system preserves the association between diagram source intent and rendered content.

Extensions

• 2a. The renderer is unavailable or fails. The system reports the diagram processing problem.

---

UC-017 Process bibliography-aware document

Level: Subfunction Primary Actor: Technical Editor Supporting Actors: Bibliography Processor Goal: Process citations and bibliography in supported workflows

Preconditions

• The project contains citation-bearing content or bibliography declarations

Guarantees

Success

• Citations and bibliography are included in supported output forms
• Round-trip ambiguities are surfaced when preservation cannot be guaranteed

Minimal

• Bibliography-related failures are explicitly reported

Main Success Scenario

1. The system encounters citation-bearing content.
2. The system resolves bibliography-related inputs.
3. The system applies bibliography-aware processing.
4. The system includes citations and bibliography in generated output.
5. The system reports unresolved or ambiguous citation conditions when present.

Extensions

• 2a. Bibliography data is missing or unresolved. The system reports bibliography-related issues.
• 3a. Citation preservation cannot be guaranteed during import. The system reports ambiguity.

---

UC-018 Execute local CLI workflow

Level: Summary Primary Actor: Build Operator Goal: Use markidocx locally through the command-line interface

Preconditions

• A local markidocx CLI is available
• Relevant project or artifact inputs are accessible

Guarantees

Success

• The actor can invoke core system functions locally
• The system returns human-readable and optionally structured outputs

Minimal

• Failed local operations produce explicit status information

Main Success Scenario

1. The actor invokes a CLI command.
2. The system interprets the requested operation.
3. The system performs the underlying function.
4. The system returns status, outputs, warnings, and errors as applicable.

Variations

• Validate project
• Build artifact
• Import DOCX
• Compare drift
• Inspect project
• List families
• Register family
• Run tests

---

UC-019 Execute REST-based workflow

Level: Summary Primary Actor: Integration Client Goal: Use markidocx through the REST interface

Preconditions

• The service is operational
• The client can submit project or artifact data

Guarantees

Success

• The client can invoke core system functions through REST
• The service returns structured machine-consumable results

Minimal

• Unsuccessful operations return explicit structured errors

Main Success Scenario

1. The client submits a request to the service.
2. The system interprets the request.
3. The system performs the requested function.
4. The system returns a structured response with status and outputs.

Variations

• Validate project
• Build artifact
• Import DOCX
• Compare drift
• List families
• Register family
• Retrieve capability metadata
• Retrieve health and version status

---

UC-020 Execute MCP-based workflow

Level: Summary Primary Actor: MCP Client Goal: Use markidocx through MCP-discoverable tools and resources

Preconditions

• An MCP-capable client is connected to the system
• The markidocx MCP interface is operational

Guarantees

Success

• The client can discover and invoke markidocx tools
• The client can retrieve project, capability, and result information

Minimal

• Unsupported tool requests are explicitly rejected or reported

Main Success Scenario

1. The client discovers available markidocx tools and resources.
2. The client chooses a tool or resource.
3. The system performs the requested operation.
4. The system returns a structured tool result or resource content.

Variations

• List templates/styles
• Inspect project
• Validate project
• Build DOCX
• Import DOCX
• Compare drift
• Run end-to-end tests
• Retrieve version metadata

---

UC-021 Run end-to-end regression on stable docs

Level: User-goal Primary Actor: Release Manager Goal: Validate the latest stable markidocx documentation corpus as canonical end-to-end testcase

Preconditions

• The latest stable documentation corpus exists as a managed markidocx project

Guarantees

Success

• The documentation corpus is processed through the required round-trip path
• The resulting validation evidence is available for release decisions

Minimal

• Failures are explicitly reported with usable evidence

Main Success Scenario

1. The actor requests end-to-end regression execution.
2. The system loads the stable documentation corpus.
3. The system validates the documentation project.
4. The system builds required output artifacts.
5. The system performs import and comparison flows as defined by the regression profile.
6. The system records and reports regression outcomes.

Extensions

• 3a. The documentation project is no longer valid. The system reports regression cannot proceed successfully.
• 5a. Drift exceeds acceptable thresholds. The system marks regression with warnings or failure.

Related Use Cases

• UC-025 Build and inspect release evidence

---

UC-022 Review warning and ambiguity report

Level: User-goal Primary Actor: Technical Editor Goal: Inspect unsupported, degraded, or ambiguous processing outcomes

Preconditions

• A prior operation produced warnings or ambiguity results

Guarantees

Success

• The actor receives a structured explanation of detected issues
• The actor can distinguish unsupported from degraded but usable outcomes

Minimal

• The original operation result remains available

Main Success Scenario

1. The actor opens or requests an operation report.
2. The system presents warnings, ambiguities, and severity classification.
3. The actor inspects the reported issues.
4. The actor uses the report to decide next steps.

---

UC-023 Retrieve system capability metadata

Level: User-goal Primary Actor: Integration Client Goal: Discover what the system supports before invoking deeper operations

Preconditions

• The system is operational

Guarantees

Success

• The actor receives capability metadata about supported feature levels, families, and interfaces

Minimal

• System state remains unchanged

Main Success Scenario

1. The actor requests capability metadata.
2. The system gathers capability information.
3. The system returns a structured capability description.

---

UC-024 Retrieve health and version status

Level: User-goal Primary Actor: Build Operator Goal: Determine whether the system is available and what version is running

Preconditions

• The system or service endpoint is reachable

Guarantees

Success

• The actor receives health and version information

Minimal

• System state remains unchanged

Main Success Scenario

1. The actor requests health or version information.
2. The system returns machine-consumable status information.

---

UC-025 Build and inspect release evidence

Level: User-goal Primary Actor: Release Manager Goal: Produce auditable evidence of release-time round-trip behavior

Preconditions

• A regression flow has been executed or is about to be executed

Guarantees

Success

• Build, import, validation, and drift evidence is assembled and inspectable
• Release decisions can reference the generated evidence

Minimal

• Missing evidence is explicitly reported

Main Success Scenario

1. The actor requests release evidence generation or review.
2. The system collects relevant validation, build, import, and drift outputs.
3. The system assembles them into a coherent evidence set.
4. The actor reviews the evidence for release decision-making.

---

8. Use Case Grouping by Functional Domain

8.1 Project Lifecycle

• UC-001 Define document project
• UC-002 Inspect project configuration
• UC-003 Validate project readiness

8.2 Build and Template Workflow

• UC-004 Build DOCX review artifact
• UC-005 Build using alternate family
• UC-012 List available families
• UC-013 Register additional template family

8.3 Round-Trip Workflow

• UC-006 Import edited DOCX into Markdown
• UC-007 Round-trip single-file document
• UC-008 Round-trip multi-file document
• UC-009 Redistribute imported edits to source files
• UC-010 Fallback to merged Markdown import
• UC-011 Detect round-trip drift
• UC-022 Review warning and ambiguity report

8.4 Feature-Level Workflow

• UC-014 Build LEVEL1 document
• UC-015 Build LEVEL3 document
• UC-016 Generate automatic diagrams
• UC-017 Process bibliography-aware document

8.5 Interface Workflow

• UC-018 Execute local CLI workflow
• UC-019 Execute REST-based workflow
• UC-020 Execute MCP-based workflow
• UC-023 Retrieve system capability metadata
• UC-024 Retrieve health and version status

8.6 Release and Governance Workflow

• UC-021 Run end-to-end regression on stable docs
• UC-025 Build and inspect release evidence

---

9. Lifecycle Metadata Guidance

Each use case in the managed catalog should support the following governance metadata:

• Status: draft, active, deprecated, retired
• Owner: responsible role or team
• Version introduced
• Last review date
• Trace links: PRD sections, FRS IDs, test suites
• Change note

Suggested default metadata model:

use_case:
  id: UC-004
  name: Build DOCX review artifact
  status: active
  owner: product-management
  version_introduced: "1.0"
  last_review: "2026-03-14"
  traces:
    prd:
      - "Section 6 Product Use Cases"
      - "Section 8 Success Criteria"
    frs:
      - "FR-201"
      - "FR-203"
      - "FR-204"
      - "FR-208"
    tests:
      - "E2E-BUILD-001"
      - "CLI-BUILD-001"
      - "REST-BUILD-001"

---

10. Suggested Traceability Anchors to FRS

Project and Manifest

• UC-001 ↔ FR-101 to FR-106
• UC-002 ↔ FR-104 to FR-105
• UC-003 ↔ FR-701 to FR-703

Build and Export

• UC-004 ↔ FR-201 to FR-209
• UC-005 ↔ FR-204 to FR-205, FR-603 to FR-610

Import and Round-Trip

• UC-006 ↔ FR-301 to FR-308
• UC-007 ↔ FR-201 to FR-308, FR-704 to FR-710
• UC-008 ↔ FR-401 to FR-407, FR-704 to FR-710
• UC-009 ↔ FR-404 to FR-407
• UC-010 ↔ FR-406
• UC ↔ FR-704 to FR-710
• UC-022 ↔ FR-1202 to FR-1205

Feature Levels

• UC-014 ↔ FR-501 to FR-506
• UC-015 ↔ FR-531 to FR-537
• UC-016 ↔ FR-533 to FR-534
• UC-017 ↔ FR-535 to FR-536

Interfaces

• UC-018 ↔ FR-801 to FR-812
• UC-019 ↔ FR-901 to FR-912
• UC-020 ↔ FR-1001 to FR-1011
• UC-023 ↔ FR-909, FR-1011
• UC-024 ↔ FR-910 to FR-911

Release and Testing

• UC-021 ↔ FR-1101 to FR-1106
• UC-025 ↔ FR-1106, FR-701 to FR-710

---

11. Optional Machine-Readable UCC Example

  id: UC-008
  name: Round-trip multi-file document
  scope: markidocx
  level: summary

  primary_actor: Technical Editor
  supporting_actors:
    - Source Mapping Context

  preconditions:
    - A valid multi-file project exists
    - Source mapping or section-origin context is available

  guarantees:
    success:
      - A single review artifact is built from multiple sources
      - Imported changes are either redistributed or clearly surfaced in fallback form
      - Drift is reported with source-awareness where possible
    minimal:
      - Source structure is not silently lost

  main_success_scenario:
    - Actor inspects the multi-file project
    - Actor validates the project
    - Actor builds a single DOCX review artifact
    - Reviewer edits the DOCX
    - Actor imports the edited DOCX into the project context
    - System attempts source-aware redistribution
    - System either redistributes content or provides a managed fallback
    - Actor runs drift comparison
    - System returns redistribution status and drift results

  extensions:
    - step: 6
      condition: redistribution is ambiguous
      outcome: system falls back to merged output and reports the condition
    - step: 8
      condition: drift affects section boundaries or identifiers
      outcome: system returns structural warnings

  includes:
    - UC-002
    - UC-003
    - UC-004
    - UC-006
    - UC-011

  status: draft
  owner: product-management
  last_review: 2026-03-14

---

12. Concise Summary

This UCC gives markidocx a proper actor-goal-centered functional backbone. It expands the earlier use cases into a governed catalog that can now serve as the bridge between:

• PRD intent
• FRS requirement groups
• acceptance test design
• later API and schema contracts

The strongest next step is to derive either:

1. an acceptance criteria catalog from these use cases, or
2. a machine-readable UCC schema pack with one YAML file per use case plus an index manifest.

xxx