@beyondwork/docx-react-component 1.0.0 → 1.0.2

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

@@ -1,430 +0,0 @@
-# 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/
-```