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

- workplans/MRKD-WP-0001-foundation-level1.md: 8-task workplan for Foundation & LEVEL1 Core (T01 scaffolding through T08 e2e harness) - CLAUDE.md: added Planned Architecture section (interface table, FR domain map, key concepts, round-trip data flow) and Development Commands stubs derived from FRS v0.2 - problems/next-steps-2026-03-14.md: implementation guide for next session — task order, dep list, state-hub task UUIDs, quality gates No code implemented yet; workstream registered in State Hub. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-14 18:18:54 +01:00
parent d298e2989d
commit c6dfc9b172
12 changed files with 4465 additions and 1 deletions
--- a/specs/MarkiDocxProductRequirementsDocument_v0.1.md
+++ b/specs/MarkiDocxProductRequirementsDocument_v0.1.md
@@ -0,0 +1,391 @@
+Below is a **PRD for the markidocx product**, structured according to your **InfoTechPrimer PRD model** and respecting the principle of **implementation independence** (no CLI flags, API routes, or architecture details).
+Implementation specifics such as CLI/REST/MCP interfaces belong in the **FRS**, which would normally follow this PRD.
+
+---
+
+# PRD
+
+*Product Requirement Document*
+
+# Product Requirements Document: markidocx
+
+## 1. Definition
+
+**markidocx** is a product that enables **reliable round-trip editing between Markdown and Microsoft Word documents** while preserving document structure and semantic intent.
+
+The product addresses a recurring coordination problem in technical documentation and knowledge workflows:
+Markdown is widely used for structured authoring and version-controlled collaboration, while Word remains the dominant format for editorial review, stakeholder collaboration, and formal document exchange.
+
+markidocx provides a controlled workflow in which:
+
+* Markdown remains the **canonical structured source**
+* Word serves as a **managed editorial interface**
+* repeated conversion cycles preserve semantic structure
+* template-driven styling separates presentation from content
+* large multi-file documents remain manageable across the editing lifecycle
+
+The product is intended for organizations that require **structured documentation workflows with Word-based collaboration**, including engineering teams, documentation teams, standards bodies, and regulated environments.
+
+---
+
+## 2. Context
+
+markidocx operates at the intersection of:
+
+* **technical documentation systems**
+* **collaborative editorial workflows**
+* **requirements and specification authoring**
+* **knowledge management infrastructures**
+
+In many modern documentation environments:
+
+* engineers and technical authors write in **Markdown**
+* documents are stored in **version-controlled repositories**
+* external stakeholders and reviewers operate primarily in **Word**
+
+This mismatch creates friction:
+
+* Word-based edits often break structured content
+* Markdown workflows are inaccessible to non-technical reviewers
+* conversion pipelines introduce structural drift
+
+markidocx exists to bridge these environments by establishing a **controlled round-trip workflow** where:
+
+* Markdown remains structurally authoritative
+* Word editing is supported within a defined semantic envelope
+* conversion processes are deterministic and inspectable
+
+The product acts as a **boundary system between structured authoring and editorial collaboration**.
+
+---
+
+## 3. Core Concepts
+
+### Round-Trip Editing
+
+Round-trip editing is the ability to export a document into another format for editing and later re-import the modified document while preserving structural meaning.
+
+markidocx establishes a disciplined round-trip process between Markdown and Word.
+
+---
+
+### Canonical Source Model
+
+The canonical source of truth is **Markdown structured documents**.
+
+Word documents generated by the system are considered **editorial projections** of the canonical source rather than independent authoritative artifacts.
+
+---
+
+### Semantic Preservation
+
+The product guarantees preservation of document semantics across editing cycles within defined feature levels.
+
+Preserved semantics include structural constructs such as headings, lists, references, and citations.
+
+---
+
+### Template-Driven Presentation
+
+Document presentation is controlled by **document templates and style definitions**.
+
+This allows the same content to be exported in different presentation forms without modifying the source.
+
+Built-in document families include:
+
+* article
+* book
+* website
+
+---
+
+### Multi-File Document Composition
+
+Large documents are often structured across multiple files for maintainability.
+
+markidocx supports multi-file composition and ensures that editing cycles do not collapse this structure unnecessarily.
+
+---
+
+### Feature Levels
+
+markidocx distinguishes between two functional feature tiers:
+
+**LEVEL1 – Core Document Structure**
+
+* headings
+* lists
+* tables
+* footnotes
+* images
+* links
+
+**LEVEL3 – Advanced Scholarly / Technical Features**
+
+* cross references
+* numbered figures
+* automatic diagrams
+* bibliography
+
+Feature levels define the guarantees the system provides during round-trip editing.
+
+---
+
+### Drift Detection
+
+Structural drift may occur when editing documents in Word.
+
+markidocx introduces mechanisms to detect and report semantic differences between:
+
+* original Markdown sources
+* re-imported Markdown versions
+
+This allows users to understand and manage structural changes.
+
+---
+
+## 4. Scope and Non-Scope
+
+### In Scope
+
+The product must support:
+
+* Markdown ↔ Word round-trip editing
+* multi-file document composition
+* template-based document styling
+* two defined feature levels (LEVEL1 and LEVEL3)
+* preservation of document structure across editing cycles
+* detection and reporting of semantic drift
+* support for editorial collaboration workflows
+* extensibility through additional document templates and styles
+* automated testing of round-trip behavior using product documentation
+
+The product must provide interfaces that enable:
+
+* local document workflows
+* automated integration into documentation pipelines
+* programmatic interaction through service interfaces
+
+---
+
+### Out of Scope
+
+The product does not attempt to:
+
+* replace word processors
+* provide a graphical document editor
+* support arbitrary Word document constructs
+* act as a full document layout system
+* enforce a specific documentation methodology
+* replace existing publishing systems
+
+markidocx focuses specifically on **structured round-trip workflows**, not full document production ecosystems.
+
+---
+
+## 5. Practical Implications
+
+Adopting markidocx introduces a structured approach to document collaboration.
+
+Benefits include:
+
+* improved collaboration between technical and non-technical stakeholders
+* preservation of structured documentation in version-controlled environments
+* reduced manual cleanup after Word-based reviews
+* deterministic document generation workflows
+* improved traceability between authored content and reviewed documents
+
+Trade-offs include:
+
+* the need to operate within supported feature boundaries
+* the requirement to use defined templates and styles
+* occasional limitations when importing highly customized Word content
+
+The system is particularly valuable for organizations that:
+
+* maintain long-lived technical documentation
+* operate cross-disciplinary teams
+* require traceable document evolution
+* manage complex specifications or manuals
+
+---
+
+## 6. Product Use Cases
+
+The product must support the following key use cases.
+
+### Technical Review Workflow
+
+A document written in Markdown is exported to Word for review by stakeholders and later re-imported with edits incorporated into the Markdown source.
+
+---
+
+### Multi-Chapter Document Editing
+
+A large multi-file document is exported as a single Word document for external review and later re-imported without collapsing the source structure.
+
+---
+
+### Specification Publishing
+
+A technical specification written in Markdown is exported using a formal template suitable for distribution and archival.
+
+---
+
+### Documentation Collaboration
+
+Technical authors maintain Markdown sources while subject matter experts provide editorial feedback using Word.
+
+---
+
+### Knowledge System Integration
+
+The product integrates with documentation pipelines, knowledge repositories, or automated publication workflows.
+
+---
+
+### Regression Testing of Documentation
+
+The product documentation itself serves as a round-trip editing test corpus, validating product functionality across releases.
+
+---
+
+## 7. Constraints and Assumptions
+
+### Constraints
+
+* Word document editing environments vary widely.
+* Markdown dialects differ across ecosystems.
+* Some Word features cannot be reliably mapped to Markdown.
+* Diagram and bibliography rendering depend on external tools.
+
+The product must therefore operate within defined semantic boundaries.
+
+---
+
+### Assumptions
+
+* Markdown remains the authoritative authoring format.
+* Word is used primarily for editing and review rather than canonical storage.
+* document structure is maintained using supported constructs.
+* editorial users operate within template-defined formatting environments.
+
+---
+
+## 8. Success Criteria
+
+markidocx is considered successful when it achieves the following outcomes.
+
+### Structural Stability
+
+Repeated Markdown → Word → Markdown cycles preserve document structure within supported feature levels.
+
+---
+
+### Editorial Accessibility
+
+Non-technical stakeholders can review and edit documents without interacting directly with Markdown sources.
+
+---
+
+### Template Flexibility
+
+Organizations can apply different document presentation styles without altering content.
+
+---
+
+### Multi-Document Scalability
+
+Large documents composed from multiple files remain manageable across editing cycles.
+
+---
+
+### Detectable Drift
+
+Structural changes introduced during editing are visible and analyzable.
+
+---
+
+### Pipeline Compatibility
+
+The product integrates into automated documentation and publishing pipelines.
+
+---
+
+### Testable Documentation
+
+The product documentation itself can be used as a stable end-to-end validation corpus.
+
+---
+
+## 9. Dependencies
+
+The product depends on:
+
+* document conversion technologies capable of translating between Markdown and Word formats
+* diagram rendering tools for automated diagrams
+* citation and bibliography processing tools
+* structured document templates
+* consistent Markdown dialect support
+
+External dependencies must be manageable without introducing excessive operational complexity.
+
+---
+
+## 10. Risks
+
+### Semantic Drift Risk
+
+Editing in Word may unintentionally alter document structure.
+
+---
+
+### Template Misuse
+
+Users may modify templates in ways that break round-trip guarantees.
+
+---
+
+### Over-complex Feature Expectations
+
+Users may expect support for all Word features, which is not feasible.
+
+---
+
+### Workflow Discipline
+
+Successful operation depends on maintaining structured authoring practices.
+
+---
+
+## 11. Related Concepts
+
+* Markdown Documentation Systems
+* Structured Authoring
+* Technical Writing Pipelines
+* Documentation-as-Code
+* Word Editorial Workflows
+* Publishing Toolchains
+* Knowledge Repositories
+
+Adjacent artifacts include:
+
+* Functional Requirements Specification (FRS)
+* Architecture Documentation
+* Technical Specifications
+* Template and Style Definitions
+* Round-Trip Validation Reports
+
+---
+
+## 12. Appendix: Product Positioning
+
+markidocx belongs to a class of tools that bridge structured authoring and editorial collaboration.
+
+Compared with typical Markdown toolchains, the product focuses specifically on **controlled editorial round-trip workflows** rather than pure publishing.
+
+Compared with office-based authoring systems, the product preserves **version-controlled structured sources**.
+
+Its value lies in enabling **structured documentation ecosystems that remain compatible with Word-centric collaboration environments**.
+
+xxx