@beyondwork/docx-react-component 1.0.0

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

@@ -0,0 +1,430 @@
+# Wave 5 - Structural Breadth And Comments Baseline
+
+**Commit message**: `Build: baseline structural fixtures and comments`
+
+## Component promotions
+
+- compatibility-and-word-validation: baseline-proved
+- comments-and-anchor-mapping: baseline-proved
+- tracked-changes-and-review-actions: baseline-proved
+
+## Scope note
+
+Wave 5 now owns the bounded proof for numbering, inline media, and comment OOXML roundtrip on top of the live Wave 4 shell. `F05` and `F06` remain preserve-only table/package fixtures on the live path rather than first-class table closure. Tracked changes remain substrate only in this wave.
+Wave 5 also uses scenario artifact `S01` (`test/fixtures/scenarios/docx/S01-sow-template.docx`) as a real-world structural and preserve-only smoke document. It supplements the frozen F03-F10 fixture proof and does not replace it.
+
+## Context7 defaults
+
+- bundle: word-editor-runtime
+- query: "comment anchor mapping, review threads, sidebar UX, and tracked-change substrate contracts"
+
+## Agent A0: cont-QA
+
+### Role prompts
+
+- docs/agents/wave-cont-qa-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "comment proof completeness, anchor remap edge cases, and honest redline repo-landed claims"
+
+### Prompt
+
+```text
+Primary goal:
+- Refuse closure if Wave 5 overclaims tracked changes or if comment proof does not cover anchor movement.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/current-state.md and docs/plans/waves/wave-4.md.
+- Read the comments and revision sections of the local feature matrix research doc.
+
+Specific expectations:
+- overlapping and edited comment anchors must be covered by proof
+- tracked changes in this wave stay repo-landed only
+- record source-vs-export validator deltas for `S01` instead of demanding a zero-finding source document
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-5-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: "integration across comment stores, anchor mappings, sidebar UI, and redline substrate"
+
+### Prompt
+
+```text
+Primary goal:
+- Reconcile comment import/export, runtime remapping, and review UI into one baseline-proved claim.
+
+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, and docs/plans/waves/wave-5.md.
+
+Specific expectations:
+- block closure if comments depend on DOM offsets
+- block closure if the sidebar can drift from runtime truth
+- block closure if tracked-change substrate mutates comment anchors implicitly
+- block closure if `S01` is used as if it were a clean release-gate fixture instead of a delta-tracked scenario artifact
+
+File ownership (only touch these paths):
+- .tmp/main-wave-launcher/integration/wave-5.md
+- .tmp/main-wave-launcher/integration/wave-5.json
+```
+
+## Agent A9: Documentation Steward
+
+### Role prompts
+
+- docs/agents/wave-documentation-role.md
+
+### Executor
+
+- profile: docs-pass
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "documenting comment baseline boundaries and redline follow-on scope"
+
+### Prompt
+
+```text
+Primary goal:
+- Update the shared plan so the repo records exactly what the comment baseline proves and what redlines still owe.
+
+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, and docs/plans/component-cutover-matrix.md.
+- Read the Wave 5 proof note.
+
+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: Comment OOXML Import And Export
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 45
+
+### Context7
+
+- bundle: word-editor-ooxml
+- query: "comments.xml, comment range markers, comment ids, and WordprocessingML comment serialization"
+
+### Skills
+
+- role-implementation
+- domain-docx-compatibility
+- domain-legal-review
+
+### Components
+
+- compatibility-and-word-validation
+- comments-and-anchor-mapping
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- src/io/ooxml/parse-comments.ts
+- src/io/export/serialize-comments.ts
+- src/review/store/comment-thread.ts
+- test/io/comment-roundtrip.test.ts
+
+### Prompt
+
+```text
+Primary goal:
+- Land comment import/export for the supported single-paragraph comment 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 the comments sections of the local research docs.
+
+Specific expectations:
+- keep unsupported multi-paragraph edit flows preserve-only
+- keep comment ids stable across import, edit, and export
+
+File ownership (only touch these paths):
+- src/io/ooxml/parse-comments.ts
+- src/io/export/serialize-comments.ts
+- src/review/store/comment-thread.ts
+- test/io/comment-roundtrip.test.ts
+```
+
+## Agent A2: Anchor Remapping And Review Runtime
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 45
+
+### Context7
+
+- bundle: word-editor-runtime
+- query: "mapping anchored ranges through edits, selection changes, and detached review stores"
+
+### Skills
+
+- role-implementation
+- domain-editor-architecture
+- domain-legal-review
+
+### Components
+
+- comments-and-anchor-mapping
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- src/review/store/comment-remapping.ts
+- src/runtime/review-runtime.ts
+- src/core/selection/review-anchors.ts
+- test/review/comment-remapping.test.ts
+
+### Prompt
+
+```text
+Primary goal:
+- Make comment anchors survive normal editing operations through runtime mappings.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/waves/specs/wave-1-review-and-ui-contracts.md.
+- Read Wave 4 review-store outputs.
+
+Specific expectations:
+- cover insertions at boundaries, deletions through anchors, and paragraph merges within the supported comment slice
+- keep remapping rules deterministic and explicit
+
+File ownership (only touch these paths):
+- src/review/store/comment-remapping.ts
+- src/runtime/review-runtime.ts
+- src/core/selection/review-anchors.ts
+- test/review/comment-remapping.test.ts
+```
+
+## Agent A3: Comment Review UI
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 40
+
+### Context7
+
+- bundle: word-editor-ui
+- query: "comment sidebars, focused review UI, anchored highlights, and resolution actions"
+
+### Skills
+
+- role-implementation
+- domain-legal-review
+
+### Components
+
+- comments-and-anchor-mapping
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- src/ui/comments/comment-sidebar.tsx
+- src/ui/comments/comment-thread-view.tsx
+- src/ui/editor-surface/comment-decorations.tsx
+- test/ui/comment-review-surface.test.tsx
+
+### Prompt
+
+```text
+Primary goal:
+- Ship a usable comment review surface without overpowering the document canvas.
+
+Required context before coding:
+- Read DESIGN.md.
+- Read 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 threads and resolution state visible but secondary
+- keep anchor decorations muted and precise
+
+File ownership (only touch these paths):
+- src/ui/comments/comment-sidebar.tsx
+- src/ui/comments/comment-thread-view.tsx
+- src/ui/editor-surface/comment-decorations.tsx
+- test/ui/comment-review-surface.test.tsx
+```
+
+## Agent A4: Tracked-Change Substrate
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 40
+
+### Context7
+
+- bundle: word-editor-ooxml
+- query: "tracked insertion/deletion data models, accept/reject contract surfaces, and revision metadata envelopes"
+
+### Skills
+
+- role-implementation
+- domain-legal-review
+
+### Components
+
+- tracked-changes-and-review-actions
+
+### Exit contract
+
+- completion: integrated
+- durability: durable
+- proof: unit
+- doc-impact: owned
+
+### Deliverables
+
+- src/review/store/revision-store.ts
+- src/review/store/revision-types.ts
+- src/ui/review/review-mode-shell.tsx
+- test/review/revision-store.test.ts
+
+### Prompt
+
+```text
+Primary goal:
+- Land the revision store substrate and review-mode shell without yet claiming baseline-proved redline round-trip.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/waves/specs/wave-1-review-and-ui-contracts.md.
+- Read the redline sections of the local research docs.
+
+Specific expectations:
+- support insertion/deletion records first
+- keep formatting revisions and moves preserve-only
+- do not yet author redline OOXML until Wave 6
+
+File ownership (only touch these paths):
+- src/review/store/revision-store.ts
+- src/review/store/revision-types.ts
+- src/ui/review/review-mode-shell.tsx
+- test/review/revision-store.test.ts
+```
+
+## Agent A5: Comment Baseline Proof
+
+### Executor
+
+- profile: proof-owner
+- retry-policy: sticky
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "comment fixture proof, thread integrity, anchor remap coverage, and compatibility reporting"
+
+### Skills
+
+- role-implementation
+- domain-docx-compatibility
+
+### Components
+
+- comments-and-anchor-mapping
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- docs/plans/waves/reviews/wave-5-comment-proof.md
+- test/fixtures/docx/F09-comments-single-paragraph.docx
+- test/fixtures/docx/F10-threaded-comments-resolve.docx
+- test/fixtures/docx/F13-comments-on-deleted-text.docx
+
+### Proof artifacts
+
+- path: .tmp/wave-5-comments/comment-anchor-report.json | kind: remap-report | required-for: baseline-proved
+- path: .tmp/wave-5-comments/thread-roundtrip-report.json | kind: roundtrip-report | required-for: baseline-proved
+- path: .tmp/wave-5-comments/comment-ui-proof.json | kind: integration-report | required-for: baseline-proved
+
+### Prompt
+
+```text
+Primary goal:
+- Produce the bounded proof bundle that justifies the comment baseline claim.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read test/fixtures/docx/README.md.
+- Read docs/reference/ooxml-compliance.md.
+
+Specific expectations:
+- include overlapping and edited-anchor cases
+- record any Word UI caveats around comments on deleted text rather than hiding them
+- run `S01` as additional scenario smoke coverage and record its validator delta separately from the F09/F10/F13 baseline fixtures
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-5-comment-proof.md
+- test/fixtures/docx/F09-comments-single-paragraph.docx
+- test/fixtures/docx/F10-threaded-comments-resolve.docx
+- test/fixtures/docx/F13-comments-on-deleted-text.docx
+- .tmp/wave-5-comments/
+```