@beyondwork/docx-react-component 1.0.0

package/docs/plans/waves/completed/wave-0.md

@@ -0,0 +1,195 @@
+# Wave 0 - Product Framing And Repository Scaffold
+
+**Commit message**: `Docs: frame the React Word Editor architecture`
+
+## Component promotions
+
+- canonical-document-model: baseline-proved
+- command-and-transaction-runtime: baseline-proved
+- comments-and-anchor-mapping: baseline-proved
+- tracked-changes-and-review-actions: baseline-proved
+- docx-import-and-normalization: baseline-proved
+- docx-export-and-serialization: baseline-proved
+- unsupported-ooxml-preservation: baseline-proved
+- compatibility-and-word-validation: baseline-proved
+- react-editor-ui: baseline-proved
+- railway-test-harness: repo-landed
+- openxml-sdk-validator-service: baseline-proved
+
+## Context7 defaults
+
+- bundle: node-typescript
+- query: "React editor architecture, schema-based document systems, OOXML round-trip safety, legal review comments, and tracked changes"
+
+## Agent A0: cont-QA
+
+### Role prompts
+
+- docs/agents/wave-cont-qa-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: none
+
+### Prompt
+
+```text
+Primary goal:
+- Verify that the initial repo framing for the React Word Editor is coherent before implementation starts.
+
+Required context before coding:
+- Read README.md and AGENTS.md.
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/roadmap.md, docs/plans/master-plan.md, and docs/plans/current-state.md.
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-0-cont-qa.md
+```
+
+## Agent A8: Integration Steward
+
+### Role prompts
+
+- docs/agents/wave-integration-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: none
+
+### Capabilities
+
+  - integration
+  - architecture-alignment
+
+### Prompt
+
+```text
+Synthesize the initial repository scaffold before documentation and cont-QA closure.
+
+Required context before coding:
+- Read README.md and AGENTS.md.
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/roadmap.md, docs/plans/master-plan.md, and docs/plans/current-state.md.
+
+File ownership (only touch these paths):
+- .tmp/main-wave-launcher/integration/wave-0.md
+- .tmp/main-wave-launcher/integration/wave-0.json
+```
+
+## Agent A9: Documentation Steward
+
+### Role prompts
+
+- docs/agents/wave-documentation-role.md
+
+### Executor
+
+- profile: docs-pass
+
+### Context7
+
+- bundle: none
+
+### Prompt
+
+```text
+Keep the project framing docs aligned with the landed Wave 0 outcomes.
+
+Required context before coding:
+- Read README.md and AGENTS.md.
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+
+File ownership (only touch these paths):
+- README.md
+- AGENTS.md
+- docs/roadmap.md
+- docs/plans/current-state.md
+- docs/plans/master-plan.md
+- docs/plans/migration.md
+- docs/plans/component-cutover-matrix.md
+- docs/plans/component-cutover-matrix.json
+```
+
+## Agent A1: Repository Scaffold And Product Architecture
+
+### Executor
+
+- profile: implement-fast
+- codex.add_dirs: docs,skills,src,test,examples
+- fallbacks: claude
+
+### Context7
+
+- bundle: node-typescript
+- query: "Node.js module layout, process spawning, and vitest test execution"
+
+### Skills
+
+- domain-editor-architecture
+- domain-docx-compatibility
+- domain-legal-review
+
+### Capabilities
+
+- editor-architecture
+- docx-compatibility
+
+### Exit contract
+
+- completion: contract
+- durability: none
+- proof: unit
+- doc-impact: owned
+
+### Components
+
+- canonical-document-model
+- command-and-transaction-runtime
+- comments-and-anchor-mapping
+- tracked-changes-and-review-actions
+- docx-import-and-normalization
+- docx-export-and-serialization
+- unsupported-ooxml-preservation
+- compatibility-and-word-validation
+- react-editor-ui
+- railway-test-harness
+- openxml-sdk-validator-service
+
+### Prompt
+
+```text
+Create the initial repository scaffold for the React Word Editor.
+
+Required context before coding:
+- Read README.md and AGENTS.md.
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/roadmap.md, docs/plans/master-plan.md, and docs/plans/current-state.md.
+
+File ownership (only touch these paths):
+- README.md
+- AGENTS.md
+- docs/README.md
+- docs/reference/repository-guidance.md
+- skills/README.md
+- skills/repo-coding-rules/
+- skills/role-implementation/
+- skills/domain-editor-architecture/
+- skills/domain-docx-compatibility/
+- skills/domain-legal-review/
+- src/
+- test/
+- examples/
+- services/
+```

package/docs/plans/waves/completed/wave-1.md

@@ -0,0 +1,379 @@
+# Wave 1 - Contract Freeze And Fixture Program
+
+**Commit message**: `Docs: freeze editor contracts and proof program`
+
+## Component promotions
+
+- canonical-document-model: baseline-proved
+- command-and-transaction-runtime: baseline-proved
+- comments-and-anchor-mapping: baseline-proved
+- tracked-changes-and-review-actions: baseline-proved
+- docx-import-and-normalization: baseline-proved
+- docx-export-and-serialization: baseline-proved
+- unsupported-ooxml-preservation: baseline-proved
+- compatibility-and-word-validation: baseline-proved
+- react-editor-ui: baseline-proved
+
+## Context7 defaults
+
+- bundle: word-editor-contracts
+- query: "ProseMirror schema and mapping contracts, React host boundaries, canonical editor snapshots, and OOXML-safe document system interfaces"
+
+## Agent A0: cont-QA
+
+### Role prompts
+
+- docs/agents/wave-cont-qa-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "contract completeness, fixture-bound proof, and avoiding overclaim in multi-agent editor plans"
+
+### Prompt
+
+```text
+Primary goal:
+- Refuse closure if the contract set, fixture plan, or component promotions are vague or internally inconsistent.
+
+Required context before coding:
+- Read README.md, DESIGN.md, and AGENTS.md.
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/master-plan.md, docs/plans/current-state.md, and docs/plans/component-cutover-matrix.md.
+- Read docs/research/docx-react-component/document_compatibility_and_testing_spec.md.
+
+Specific expectations:
+- fail if file ownership overlaps materially
+- fail if proof surfaces are narrative instead of machine-checkable
+- fail if any promoted component lacks an implementation owner in later waves
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-1-cont-qa.md
+```
+
+## Agent A8: Integration Steward
+
+### Role prompts
+
+- docs/agents/wave-integration-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: word-editor-contracts
+- query: "cross-component contract coherence, interface boundaries, and implementation-ready wave handoff"
+
+### Prompt
+
+```text
+Primary goal:
+- Reconcile the design packet, contract docs, and shared plan so Wave 2 can start implementation without re-deriving the architecture.
+
+Required context before coding:
+- Read DESIGN.md and docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/master-plan.md, docs/plans/current-state.md, and docs/plans/component-cutover-matrix.json.
+- Read docs/research/docx-react-component/Canonical Document Schema Specification for a React-based Word-compatible Editor.md.
+- Read docs/research/docx-react-component/React Component Architecture and Front-End Structure Specification for a Word-Compatible Legal Review Editor.md.
+
+Specific expectations:
+- reject handoff if the fixture plan does not cover comments, revisions, preservation, and malformed docs
+- reject handoff if the React shell and runtime ownership boundary remains ambiguous
+
+File ownership (only touch these paths):
+- .tmp/main-wave-launcher/integration/wave-1.md
+- .tmp/main-wave-launcher/integration/wave-1.json
+```
+
+## Agent A9: Documentation Steward
+
+### Role prompts
+
+- docs/agents/wave-documentation-role.md
+
+### Executor
+
+- profile: docs-pass
+
+### Context7
+
+- bundle: word-editor-contracts
+- query: "API, architecture, and compatibility documentation alignment for a Word-compatible React component"
+
+### Prompt
+
+```text
+Primary goal:
+- Keep the shared-plan docs aligned with the frozen contract set and the later wave sequence.
+
+Required context before coding:
+- Read README.md, DESIGN.md, and AGENTS.md.
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/master-plan.md, docs/plans/current-state.md, docs/plans/migration.md, and docs/plans/component-cutover-matrix.md.
+
+File ownership (only touch these paths):
+- README.md
+- AGENTS.md
+- docs/roadmap.md
+- docs/plans/master-plan.md
+- docs/plans/current-state.md
+- docs/plans/migration.md
+- docs/plans/component-cutover-matrix.md
+- docs/plans/component-cutover-matrix.json
+- docs/plans/waves/README.md
+```
+
+## Agent A1: Architecture Design Packet
+
+### Role prompts
+
+- docs/agents/wave-design-role.md
+
+### Executor
+
+- profile: design-pass
+- budget.minutes: 35
+
+### Context7
+
+- bundle: word-editor-contracts
+- query: "schema-first editor architecture, global position mapping, host APIs, and design packet structure for implementation handoff"
+
+### Skills
+
+- role-design
+- domain-editor-architecture
+- domain-docx-compatibility
+
+### Components
+
+- canonical-document-model
+- command-and-transaction-runtime
+- docx-import-and-normalization
+- docx-export-and-serialization
+- unsupported-ooxml-preservation
+- compatibility-and-word-validation
+- react-editor-ui
+
+### Exit contract
+
+- completion: contract
+- durability: durable
+- proof: unit
+- doc-impact: owned
+
+### Deliverables
+
+- docs/plans/waves/design/wave-1-a1.md
+- docs/plans/waves/specs/wave-1-component-boundaries.md
+
+### Prompt
+
+```text
+Primary goal:
+- Produce the implementation-ready design packet that freezes subsystem boundaries and the wave sequence for the rest of v1.
+
+Required context before coding:
+- Read README.md, DESIGN.md, and AGENTS.md.
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/master-plan.md, docs/plans/current-state.md, and docs/plans/component-cutover-matrix.json.
+- Read all files under docs/research/docx-react-component/.
+
+Specific expectations:
+- freeze one shared coordinate-space strategy for selections, comment anchors, revisions, and opaque fragments
+- make the runtime/UI boundary explicit enough that React never becomes source of truth
+- name the exact proof surfaces each later wave will own
+
+File ownership (only touch these paths):
+- docs/plans/waves/design/wave-1-a1.md
+- docs/plans/waves/specs/wave-1-component-boundaries.md
+```
+
+## Agent A2: Runtime And Host Contract Lock
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 40
+
+### Context7
+
+- bundle: word-editor-contracts
+- query: "TypeScript public interfaces, snapshot contracts, imperative refs, and ProseMirror transaction-facing APIs"
+
+### Skills
+
+- role-implementation
+- domain-editor-architecture
+
+### Components
+
+- canonical-document-model
+- command-and-transaction-runtime
+- react-editor-ui
+
+### Exit contract
+
+- completion: contract
+- durability: durable
+- proof: unit
+- doc-impact: owned
+
+### Deliverables
+
+- docs/plans/waves/specs/wave-1-runtime-contracts.md
+- docs/reference/public-api.md
+- src/api/README.md
+
+### Prompt
+
+```text
+Primary goal:
+- Freeze the public host contract, runtime event model, and snapshot boundaries.
+
+Required context before coding:
+- Read README.md, DESIGN.md, and docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/research/docx-react-component/Canonical Document Schema Specification for a React-based Word-compatible Editor.md.
+- Read docs/research/docx-react-component/React Component Architecture and Front-End Structure Specification for a Word-Compatible Legal Review Editor.md.
+
+Specific expectations:
+- standardize on WordReviewEditor and replace any residual WordEditor naming drift
+- make uncontrolled versus replace-on-change controlled behavior explicit
+- define exact snapshot, event, warning, and error envelopes
+
+File ownership (only touch these paths):
+- docs/plans/waves/specs/wave-1-runtime-contracts.md
+- docs/reference/public-api.md
+- src/api/README.md
+```
+
+## Agent A3: OOXML, Preservation, And Fixture Contract Lock
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 40
+
+### Context7
+
+- bundle: word-editor-ooxml
+- query: "OPC package contracts, OpenXmlValidator usage, markup compatibility preservation, and fixture-driven round-trip validation"
+
+### Skills
+
+- role-implementation
+- domain-docx-compatibility
+
+### Components
+
+- docx-import-and-normalization
+- docx-export-and-serialization
+- unsupported-ooxml-preservation
+- compatibility-and-word-validation
+
+### Exit contract
+
+- completion: contract
+- durability: durable
+- proof: unit
+- doc-impact: owned
+
+### Deliverables
+
+- docs/plans/waves/specs/wave-1-ooxml-contracts.md
+- docs/reference/ooxml-compliance.md
+- test/fixtures/docx/README.md
+
+### Prompt
+
+```text
+Primary goal:
+- Freeze the package-preservation model, feature-class contract, and F01-F21 fixture program.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/research/docx-react-component/document_compatibility_and_testing_spec.md.
+- Read docs/research/docx-react-component/Feature Compatibility Matrix for a React Word Compatible Legal Editor v1.md.
+
+Specific expectations:
+- treat the Microsoft Open XML SDK as validation-only, never as the editor's transformation engine
+- define exactly when the editor preserves, locks, warns, blocks, or fails
+- map each fixture to one or more proof-bearing waves
+
+File ownership (only touch these paths):
+- docs/plans/waves/specs/wave-1-ooxml-contracts.md
+- docs/reference/ooxml-compliance.md
+- test/fixtures/docx/README.md
+```
+
+## Agent A4: Review And UI Contract Lock
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 40
+
+### Context7
+
+- bundle: word-editor-ui
+- query: "review-oriented editor UI, contextual controls, comment sidebars, and React shell composition without DOM truth"
+
+### Skills
+
+- role-implementation
+- domain-legal-review
+- domain-editor-architecture
+
+### Components
+
+- comments-and-anchor-mapping
+- tracked-changes-and-review-actions
+- react-editor-ui
+
+### Exit contract
+
+- completion: contract
+- durability: durable
+- proof: unit
+- doc-impact: owned
+
+### Deliverables
+
+- docs/plans/waves/specs/wave-1-review-and-ui-contracts.md
+- src/review/README.md
+- src/ui/README.md
+
+### Prompt
+
+```text
+Primary goal:
+- Freeze the review model boundary and the minimal calm UI contract that later implementation waves must respect.
+
+Required context before coding:
+- Read DESIGN.md and docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/research/docx-react-component/React Component Architecture and Front-End Structure Specification for a Word-Compatible Legal Review Editor.md.
+- Read docs/research/docx-react-component/Feature Compatibility Matrix for a React Word Compatible Legal Editor v1.md.
+
+Specific expectations:
+- keep comments and revisions out of the content tree
+- keep the editor canvas primary and the review chrome secondary
+- define the locked/opaque region behavior up front so preservation and UI do not drift later
+
+File ownership (only touch these paths):
+- docs/plans/waves/specs/wave-1-review-and-ui-contracts.md
+- src/review/README.md
+- src/ui/README.md
+```