@beyondwork/docx-react-component 1.0.0

package/docs/plans/waves/wave-23.md

@@ -0,0 +1,295 @@
+# Wave 23 - Legal Workflow Features
+
+**Commit message**: `Build: version compare and legal semantics`
+
+## Project profile
+
+- project: React Word Editor
+- new-project: no
+- oversight-mode: dark-factory
+- lane: main
+
+## Sequencing note
+
+- Phase 5 of the shipping roadmap. The features that make this a legal tool.
+
+## Reference rule
+
+- Read the roadmap, current-state, and master-plan before execution.
+
+## Component promotions
+
+- version-compare-engine: baseline-proved
+
+## Context7 defaults
+
+- bundle: word-editor-testing
+- query: "document comparison, tracked changes diff, cross-references, defined terms, bookmarks, legal document editing"
+
+## Agent A0: cont-QA
+
+### Role prompts
+
+- docs/agents/wave-cont-qa-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: none
+- query: "Architecture evaluation only; repository docs remain canonical"
+
+### Deliverables
+
+- docs/plans/waves/reviews/wave-23-cont-qa.md
+
+### Prompt
+
+```text
+Primary goal:
+- Verify compare and legal features work end-to-end.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/roadmap.md
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-23-cont-qa.md
+
+Output:
+- Summarize the cont-QA verdict.
+```
+
+## Agent A8: Integration Steward
+
+### Role prompts
+
+- docs/agents/wave-integration-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: none
+- query: "Integration synthesis only; repository docs remain canonical"
+
+### Capabilities
+
+- integration
+- docs-shared-plan
+
+### Deliverables
+
+- .tmp/main-wave-launcher/integration/wave-23.md
+- .tmp/main-wave-launcher/integration/wave-23.json
+
+### Prompt
+
+```text
+Primary goal:
+- Synthesize Wave 23 state.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/plans/current-state.md
+
+File ownership (only touch these paths):
+- .tmp/main-wave-launcher/integration/wave-23.md
+- .tmp/main-wave-launcher/integration/wave-23.json
+
+Output:
+- Integration verdict and closure recommendation.
+```
+
+## Agent A9: Documentation Steward
+
+### Role prompts
+
+- docs/agents/wave-documentation-role.md
+
+### Executor
+
+- profile: docs-pass
+
+### Context7
+
+- bundle: none
+- query: "Shared plan documentation only; repository docs remain canonical"
+
+### Deliverables
+
+- 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
+
+### Prompt
+
+```text
+Primary goal:
+- Keep shared plan docs aligned with Wave 23.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/plans/current-state.md
+
+File ownership (only touch these paths):
+- 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
+
+Output:
+- Summarize shared doc updates.
+```
+
+## Agent A1: Version Compare Engine
+
+### Executor
+
+- profile: implement-claude
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "canonical document diff, version snapshot, tracked changes export, compare view rendering"
+
+### Components
+
+- version-compare-engine
+
+### Deliverables
+
+- src/compare/snapshot.ts
+- src/compare/diff-engine.ts
+- src/compare/export-redlines.ts
+- test/compare/diff-engine.test.ts
+- test/compare/compare-roundtrip.test.ts
+- .tmp/wave-23-compare-proof/test-summary.json
+
+### Proof artifacts
+
+- path: .tmp/wave-23-compare-proof/test-summary.json | kind: proof-bundle | required-for: baseline-proved
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: none
+
+### Prompt
+
+```text
+Primary goal:
+- Build the version compare engine: snapshot, diff, and redline export.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- Read src/model/canonical-document.ts for the document model.
+- Read src/io/export/ for the export pipeline.
+- Read src/review/ for revision and comment stores.
+- Read docs/roadmap.md Phase 5 requirements.
+
+File ownership (only touch these paths):
+- src/compare/snapshot.ts
+- src/compare/diff-engine.ts
+- src/compare/export-redlines.ts
+- test/compare/diff-engine.test.ts
+- test/compare/compare-roundtrip.test.ts
+- .tmp/wave-23-compare-proof/test-summary.json
+
+Requirements:
+1) Snapshot versioning: save named document versions from canonical model.
+2) Diff engine: compare two canonical documents, produce changeset.
+3) Export: produce a .docx with changes tracked as Word revision marks.
+4) Tests for diff correctness and round-trip fidelity.
+
+Validation:
+- pnpm test:repo
+
+Output:
+- Summarize landed implementation and gaps.
+```
+
+## Agent A2: Legal Semantics
+
+### Executor
+
+- profile: implement-claude
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "OOXML cross-references, bookmarks, defined terms, legal document parsing"
+
+### Components
+
+- version-compare-engine
+
+### Deliverables
+
+- src/legal/cross-references.ts
+- src/legal/defined-terms.ts
+- src/legal/bookmarks.ts
+- test/legal/cross-references.test.ts
+- test/legal/defined-terms.test.ts
+- .tmp/wave-23-compare-proof/legal-semantics.json
+
+### Proof artifacts
+
+- path: .tmp/wave-23-compare-proof/legal-semantics.json | kind: proof-bundle | required-for: baseline-proved
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: unit
+- doc-impact: none
+
+### Prompt
+
+```text
+Primary goal:
+- Add legal document semantics: cross-references, defined terms, and bookmarks.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- Read src/io/ooxml/parse-main-document.ts for OOXML parsing.
+- Read src/model/canonical-document.ts for the document model.
+- Read docs/reference/ooxml-compliance.md for relevant elements.
+- Read docs/roadmap.md Phase 5 requirements.
+
+File ownership (only touch these paths):
+- src/legal/cross-references.ts
+- src/legal/defined-terms.ts
+- src/legal/bookmarks.ts
+- test/legal/cross-references.test.ts
+- test/legal/defined-terms.test.ts
+- .tmp/wave-23-compare-proof/legal-semantics.json
+
+Requirements:
+1) Cross-references: parse w:ref elements, detect cross-ref patterns.
+2) Defined terms: detect and catalog defined terms in legal documents.
+3) Bookmarks: parse w:bookmarkStart/End, preserve through round-trip.
+4) Tests for parsing and detection logic.
+
+Validation:
+- pnpm test:repo
+
+Output:
+- Summarize landed implementation and gaps.
+```

package/docs/plans/waves/wave-24.md

@@ -0,0 +1,286 @@
+# Wave 24 - Production Hardening
+
+**Commit message**: `Build: production hardening — performance, accessibility, resilience`
+
+## Project profile
+
+- project: React Word Editor
+- new-project: no
+- oversight-mode: dark-factory
+- lane: main
+
+## Sequencing note
+
+- Phase 6 of the shipping roadmap. Final docx wave before xlsx track begins.
+
+## Reference rule
+
+- Read the roadmap, current-state, and master-plan before execution.
+
+## Component promotions
+
+- production-hardening: baseline-proved
+
+## Context7 defaults
+
+- bundle: word-editor-testing
+- query: "React performance optimization, virtual scrolling, WCAG accessibility, ProseMirror large documents, memory profiling"
+
+## Agent A0: cont-QA
+
+### Role prompts
+
+- docs/agents/wave-cont-qa-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: none
+- query: "Architecture evaluation only; repository docs remain canonical"
+
+### Deliverables
+
+- docs/plans/waves/reviews/wave-24-cont-qa.md
+
+### Prompt
+
+```text
+Primary goal:
+- Verify performance, accessibility, and resilience meet exit criteria.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/roadmap.md
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-24-cont-qa.md
+
+Output:
+- Summarize the cont-QA verdict.
+```
+
+## Agent A8: Integration Steward
+
+### Role prompts
+
+- docs/agents/wave-integration-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: none
+- query: "Integration synthesis only; repository docs remain canonical"
+
+### Capabilities
+
+- integration
+- docs-shared-plan
+
+### Deliverables
+
+- .tmp/main-wave-launcher/integration/wave-24.md
+- .tmp/main-wave-launcher/integration/wave-24.json
+
+### Prompt
+
+```text
+Primary goal:
+- Synthesize Wave 24 state.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/plans/current-state.md
+
+File ownership (only touch these paths):
+- .tmp/main-wave-launcher/integration/wave-24.md
+- .tmp/main-wave-launcher/integration/wave-24.json
+
+Output:
+- Integration verdict and closure recommendation.
+```
+
+## Agent A9: Documentation Steward
+
+### Role prompts
+
+- docs/agents/wave-documentation-role.md
+
+### Executor
+
+- profile: docs-pass
+
+### Context7
+
+- bundle: none
+- query: "Shared plan documentation only; repository docs remain canonical"
+
+### Deliverables
+
+- 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
+
+### Prompt
+
+```text
+Primary goal:
+- Close shared plan docs for the docx track before xlsx begins.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/plans/current-state.md
+
+File ownership (only touch these paths):
+- 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
+
+Output:
+- Summarize shared doc updates and docx-track closure status.
+```
+
+## Agent A1: Performance Optimization
+
+### Executor
+
+- profile: implement-claude
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "ProseMirror performance, large document rendering, virtual scrolling, lazy loading"
+
+### Components
+
+- production-hardening
+
+### Deliverables
+
+- src/runtime/virtualized-rendering.ts
+- test/performance/large-document.test.ts
+- test/performance/memory-stability.test.ts
+- .tmp/wave-24-hardening-proof/perf-results.json
+
+### Proof artifacts
+
+- path: .tmp/wave-24-hardening-proof/perf-results.json | kind: proof-bundle | required-for: baseline-proved
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: unit
+- doc-impact: none
+
+### Prompt
+
+```text
+Primary goal:
+- Make the editor handle large documents performantly.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- Read src/runtime/document-runtime.ts for the editor runtime.
+- Read src/ui/WordReviewEditor.tsx for the component tree.
+- Read docs/roadmap.md Phase 6 requirements.
+
+File ownership (only touch these paths):
+- src/runtime/virtualized-rendering.ts
+- test/performance/large-document.test.ts
+- test/performance/memory-stability.test.ts
+- .tmp/wave-24-hardening-proof/perf-results.json
+
+Requirements:
+1) 100-page document: target < 3 second load time.
+2) No memory growth over extended editing simulation.
+3) Performance test with a programmatically generated large document.
+4) Memory stability test.
+
+Validation:
+- pnpm test:repo
+
+Output:
+- Summarize performance results and remaining gaps.
+```
+
+## Agent A2: Accessibility And Resilience
+
+### Executor
+
+- profile: implement-claude
+
+### Context7
+
+- bundle: word-editor-ui
+- query: "WCAG 2.1 AA, ARIA roles, keyboard navigation, focus management, malformed docx handling"
+
+### Components
+
+- production-hardening
+
+### Deliverables
+
+- src/ui/WordReviewEditor.tsx
+- test/accessibility/wcag-audit.test.ts
+- test/resilience/malformed-docx.test.ts
+- .tmp/wave-24-hardening-proof/a11y-results.json
+
+### Proof artifacts
+
+- path: .tmp/wave-24-hardening-proof/a11y-results.json | kind: proof-bundle | required-for: baseline-proved
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: unit
+- doc-impact: none
+
+### Prompt
+
+```text
+Primary goal:
+- Make the editor accessible and resilient to malformed input.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- Read src/ui/WordReviewEditor.tsx for the component.
+- Read src/io/opc/corrupt-package.ts for error handling patterns.
+- Read test/validation/malformed-doc.test.ts for existing malformed doc tests.
+- Read docs/roadmap.md Phase 6 requirements.
+
+File ownership (only touch these paths):
+- src/ui/WordReviewEditor.tsx
+- test/accessibility/wcag-audit.test.ts
+- test/resilience/malformed-docx.test.ts
+- .tmp/wave-24-hardening-proof/a11y-results.json
+
+Requirements:
+1) WCAG 2.1 AA: proper ARIA roles, keyboard navigation, focus management.
+2) Graceful error handling for malformed .docx files.
+3) Tests for accessibility assertions.
+4) Tests for malformed document handling.
+
+Validation:
+- pnpm test:repo
+
+Output:
+- Summarize accessibility and resilience results.
+```