@beyondwork/docx-react-component 1.0.0

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

@@ -0,0 +1,435 @@
+# Wave 3 - Core Text Round-Trip Baseline
+
+**Commit message**: `Build: baseline the core text round-trip slice`
+
+## Component promotions
+
+- canonical-document-model: baseline-proved
+- command-and-transaction-runtime: baseline-proved
+- docx-import-and-normalization: baseline-proved
+- docx-export-and-serialization: baseline-proved
+- compatibility-and-word-validation: baseline-proved
+- react-editor-ui: baseline-proved
+- openxml-sdk-validator-service: baseline-proved
+
+## Context7 defaults
+
+- bundle: word-editor-ooxml
+- query: "WordprocessingML text structure, whitespace handling, hyperlinks, validation, and baseline fixture proof"
+
+## Agent A0: cont-QA
+
+### Role prompts
+
+- docs/agents/wave-cont-qa-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "baseline-proof closure, fixture sufficiency, and regression visibility"
+
+### Prompt
+
+```text
+Primary goal:
+- Refuse closure unless Wave 3 produces machine-visible baseline proof for the core text slice.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/reference/ooxml-compliance.md.
+- Read docs/plans/master-plan.md, docs/plans/current-state.md, and docs/plans/waves/wave-2.md.
+
+Specific expectations:
+- fail if the promoted baseline lacks fixture-backed import, edit, export, and validator evidence
+- fail if the UI proof does not cover selection and command invocation through the runtime shell
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-3-cont-qa.md
+```
+
+## Agent A8: Integration Steward
+
+### Role prompts
+
+- docs/agents/wave-integration-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: word-editor-runtime
+- query: "reconciling runtime, serializer, validator, and UI proof into one baseline claim"
+
+### Prompt
+
+```text
+Primary goal:
+- Decide whether the core text slice actually reached baseline-proved, not merely repo-landed with hopeful tests.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/master-plan.md and docs/plans/current-state.md.
+- Read docs/plans/waves/wave-3.md.
+
+Specific expectations:
+- missing proof artifacts are blocking
+- SDK validation errors are blocking
+- any text command path that bypasses mapping or runtime dispatch is blocking
+
+File ownership (only touch these paths):
+- .tmp/main-wave-launcher/integration/wave-3.md
+- .tmp/main-wave-launcher/integration/wave-3.json
+```
+
+## Agent A9: Documentation Steward
+
+### Role prompts
+
+- docs/agents/wave-documentation-role.md
+
+### Executor
+
+- profile: docs-pass
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "documenting what baseline-proved means for the core text slice and what still remains out of scope"
+
+### Prompt
+
+```text
+Primary goal:
+- Update the shared plan with the exact baseline that landed and the exact remaining proof gap for structural and review features.
+
+Required context before coding:
+- 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.
+- Read Wave 3 proof notes.
+
+File ownership (only touch these paths):
+- 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
+```
+
+## Agent A1: Core Text Commands And Mappings
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 45
+
+### Context7
+
+- bundle: word-editor-runtime
+- query: "text transactions, marks, positions, selections, and deterministic mapping for editor cores"
+
+### Skills
+
+- role-implementation
+- domain-editor-architecture
+
+### Components
+
+- canonical-document-model
+- command-and-transaction-runtime
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- src/core/schema/text-schema.ts
+- src/core/commands/text-commands.ts
+- src/core/state/text-transaction.ts
+- test/core/text-commands.test.ts
+
+### Prompt
+
+```text
+Primary goal:
+- Make the core text editing path deterministic enough for baseline import-edit-export proof.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/waves/wave-2.md.
+- Read docs/plans/waves/specs/wave-1-runtime-contracts.md.
+
+Specific expectations:
+- cover text insert/delete, paragraph split/merge, whitespace retention, tab insertion, and hard breaks
+- keep mapping outputs stable for later comment and revision remapping
+
+File ownership (only touch these paths):
+- src/core/schema/text-schema.ts
+- src/core/commands/text-commands.ts
+- src/core/state/text-transaction.ts
+- test/core/text-commands.test.ts
+```
+
+## Agent A2: Text Import, Export, And Normalization
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 45
+
+### Context7
+
+- bundle: word-editor-ooxml
+- query: "WordprocessingML paragraphs, runs, text nodes, xml:space preserve, breaks, tabs, headings, and hyperlinks"
+
+### Skills
+
+- role-implementation
+- domain-docx-compatibility
+
+### Components
+
+- docx-import-and-normalization
+- docx-export-and-serialization
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- src/io/normalize/normalize-text.ts
+- src/io/ooxml/parse-main-document.ts
+- src/io/export/serialize-main-document.ts
+- test/io/text-roundtrip.test.ts
+
+### Prompt
+
+```text
+Primary goal:
+- Baseline the text import/export slice for paragraphs, runs, whitespace, breaks, headings, and hyperlinks.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/reference/ooxml-compliance.md.
+- Read docs/research/docx-react-component/Feature Compatibility Matrix for a React Word Compatible Legal Editor v1.md.
+
+Specific expectations:
+- honor xml:space preservation
+- keep heading semantics style-based rather than CSS-based
+- preserve unsupported inline content as opaque placeholders instead of flattening it
+
+File ownership (only touch these paths):
+- src/io/normalize/normalize-text.ts
+- src/io/ooxml/parse-main-document.ts
+- src/io/export/serialize-main-document.ts
+- test/io/text-roundtrip.test.ts
+```
+
+## Agent A3: Core Surface And Compatibility UI
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 40
+
+### Context7
+
+- bundle: word-editor-ui
+- query: "minimal editor chrome, contextual toolbar actions, status surfaces, and compatibility panel composition"
+
+### Skills
+
+- role-implementation
+- domain-legal-review
+
+### Components
+
+- react-editor-ui
+- compatibility-and-word-validation
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- src/ui/toolbar/core-toolbar.tsx
+- src/ui/compatibility/compatibility-panel.tsx
+- src/ui/status/status-bar.tsx
+- test/ui/core-text-editor.test.tsx
+
+### Prompt
+
+```text
+Primary goal:
+- Expose the baseline text slice through a calm UI that shows compatibility warnings and document state without ribbon drift.
+
+Required context before coding:
+- Read DESIGN.md and docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/waves/specs/wave-1-review-and-ui-contracts.md.
+
+Specific expectations:
+- keep controls contextual and compact
+- surface preserve-only and unsupported-fatal states clearly
+- make the status bar reflect runtime truth instead of UI-local guesses
+
+File ownership (only touch these paths):
+- src/ui/toolbar/core-toolbar.tsx
+- src/ui/compatibility/compatibility-panel.tsx
+- src/ui/status/status-bar.tsx
+- test/ui/core-text-editor.test.tsx
+```
+
+## Agent A4: Core Fixture And Baseline Proof
+
+### Executor
+
+- profile: proof-owner
+- retry-policy: sticky
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "fixture-based baseline proof, SDK validation reporting, and integration test artifact bundling"
+
+### Skills
+
+- role-implementation
+- domain-docx-compatibility
+
+### Components
+
+- compatibility-and-word-validation
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- docs/plans/waves/reviews/wave-3-core-proof.md
+- test/fixtures/docx/F01-basic-contract.docx
+- test/fixtures/docx/F02-headings-styles.docx
+- test/fixtures/docx/F08-hyperlinks.docx
+
+### Proof artifacts
+
+- path: .tmp/wave-3-core-text/text-roundtrip-report.json | kind: roundtrip-report | required-for: baseline-proved
+- path: .tmp/wave-3-core-text/sdk-validation-report.json | kind: validation-report | required-for: baseline-proved
+- path: .tmp/wave-3-core-text/ui-smoke-report.json | kind: integration-report | required-for: baseline-proved
+
+### Prompt
+
+```text
+Primary goal:
+- Produce the bounded proof bundle for the core text baseline using the Wave 3 fixture set and the local validator.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/reference/ooxml-compliance.md.
+- Read test/fixtures/docx/README.md.
+
+Specific expectations:
+- prove import, edit, export, and validation on the declared fixture set
+- write machine-readable reports under .tmp/wave-3-core-text/
+- fail closed if any proof step requires manual interpretation to call PASS
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-3-core-proof.md
+- test/fixtures/docx/F01-basic-contract.docx
+- test/fixtures/docx/F02-headings-styles.docx
+- test/fixtures/docx/F08-hyperlinks.docx
+- .tmp/wave-3-core-text/
+```
+
+## Agent A5: Open XML Validator Service Baseline
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 35
+
+### Context7
+
+- bundle: validator-dotnet
+- query: "ASP.NET minimal APIs, OpenXmlValidator, multipart uploads, and structured validation responses"
+
+### Skills
+
+- role-implementation
+- role-infra
+
+### Components
+
+- openxml-sdk-validator-service
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- services/openxml-validator/Program.cs
+- services/openxml-validator/README.md
+- services/openxml-validator/OpenXmlValidator.Api.csproj
+- docs/plans/waves/reviews/wave-3-validator-proof.md
+
+### Proof artifacts
+
+- path: .tmp/wave-3-validator/health.json | kind: live-status | required-for: baseline-proved
+- path: .tmp/wave-3-validator/validate-smoke.json | kind: validation-report | required-for: baseline-proved
+
+### Prompt
+
+```text
+Primary goal:
+- Turn the validator scaffold into a baseline-proved internal service contract with structured responses and runnable smoke proof.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/reference/ooxml-compliance.md.
+- Read services/openxml-validator/README.md.
+
+Specific expectations:
+- keep the service validation-only
+- return package and SDK findings as distinct machine-readable collections
+- keep local run instructions accurate for the current repo
+
+File ownership (only touch these paths):
+- services/openxml-validator/Program.cs
+- services/openxml-validator/README.md
+- services/openxml-validator/OpenXmlValidator.Api.csproj
+- docs/plans/waves/reviews/wave-3-validator-proof.md
+- .tmp/wave-3-validator/
+```