@beyondwork/docx-react-component 1.0.0

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

@@ -0,0 +1,430 @@
+# Wave 6 - Preservation Baseline And Redline Substrate
+
+**Commit message**: `Build: baseline preservation and land redline substrate`
+
+## Component promotions
+
+- unsupported-ooxml-preservation: baseline-proved
+- tracked-changes-and-review-actions: baseline-proved
+
+## Scope note
+
+Wave 6 owns the preservation baseline and the bounded source-backed redline slice. It proves F11 run-level insertions or deletions plus F12 paragraph-mark accept or reject on the source-backed runtime/export path, but tracked changes still do not reach `baseline-proved` overall because broader imported-redline freeform editing can diverge from source-backed replay and block export.
+Wave 6 uses scenario artifact `S02` (`test/fixtures/scenarios/docx/S02-bw-partner-user-licence-agreement-redlines.docx`) as the primary real-world review scenario alongside F11-F14. It supplements the frozen revision fixtures and does not replace them.
+
+## Context7 defaults
+
+- bundle: word-editor-ooxml
+- query: "Word revision markup, accept/reject behavior, and preservation substrates for unsupported OOXML"
+
+## Agent A0: cont-QA
+
+### Role prompts
+
+- docs/agents/wave-cont-qa-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "redline proof completeness, accept/reject safety, and preservation-scope honesty"
+
+### Prompt
+
+```text
+Primary goal:
+- Refuse closure unless the bounded supported redline slice is proved and preservation stays honestly bounded.
+
+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-5.md.
+- Read the revisions and preserve-only sections of the local research docs.
+
+Specific expectations:
+- accept/reject must be covered by machine-visible proof
+- paragraph-mark revisions must resolve through the runtime-owned review path and source-backed export
+- tracked moves and formatting revisions must remain preserve-only
+- preservation in this wave is baseline-proved for the opaque-fragment and source-backed session substrate, but full preserved-part proof still belongs to Wave 7
+- record source-vs-export validator deltas for `S02`; do not require the source document to start SDK-clean
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-6-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 of revision stores, OOXML redline import/export, review UI, and preservation substrate"
+
+### Prompt
+
+```text
+Primary goal:
+- Decide whether the bounded redline slice and preservation substrate are coherently integrated while the broader imported-redline divergence stays explicit.
+
+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-6.md.
+
+Specific expectations:
+- block closure if revision state and comment anchors conflict silently
+- block closure if preserve-only markup is rewritten during accept/reject
+- block closure if `S02` loses existing review markup or is reported with a flattened validator story
+- broader imported-redline freeform divergence may remain a documented Wave 7 follow-on, but it must not be hidden or mislabeled as an F12 gap
+
+File ownership (only touch these paths):
+- .tmp/main-wave-launcher/integration/wave-6.md
+- .tmp/main-wave-launcher/integration/wave-6.json
+```
+
+## Agent A9: Documentation Steward
+
+### Role prompts
+
+- docs/agents/wave-documentation-role.md
+
+### Executor
+
+- profile: docs-pass
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "documenting exactly which redlines are baseline-proved and which structures remain preserve-only"
+
+### Prompt
+
+```text
+Primary goal:
+- Update shared-plan docs so the source-backed redline proof, preservation baseline, and remaining imported-redline divergence are explicit.
+
+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 6 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: Revision Store And Review Actions
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 45
+
+### Context7
+
+- bundle: word-editor-runtime
+- query: "revision records, accept/reject flows, transaction integration, and review-state reducers"
+
+### Skills
+
+- role-implementation
+- domain-editor-architecture
+- domain-legal-review
+
+### Components
+
+- tracked-changes-and-review-actions
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- src/review/store/revision-actions.ts
+- src/core/commands/review-commands.ts
+- src/runtime/revision-runtime.ts
+- test/review/revision-actions.test.ts
+
+### Prompt
+
+```text
+Primary goal:
+- Land deterministic accept/reject behavior for supported insertions and deletions.
+
+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 5 revision-store substrate outputs.
+
+Specific expectations:
+- keep revision actions purely runtime-driven
+- make unsupported structural revisions explicit preserve-only cases
+
+File ownership (only touch these paths):
+- src/review/store/revision-actions.ts
+- src/core/commands/review-commands.ts
+- src/runtime/revision-runtime.ts
+- test/review/revision-actions.test.ts
+```
+
+## Agent A2: Revision OOXML Import And Export
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 45
+
+### Context7
+
+- bundle: word-editor-ooxml
+- query: "w:ins, w:del, paragraph-mark revisions, author metadata, and WordprocessingML revision boundaries"
+
+### Skills
+
+- role-implementation
+- domain-docx-compatibility
+- domain-legal-review
+
+### Components
+
+- tracked-changes-and-review-actions
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- src/io/ooxml/parse-revisions.ts
+- src/io/export/serialize-revisions.ts
+- src/io/ooxml/revision-boundaries.ts
+- test/io/revision-roundtrip.test.ts
+
+### Prompt
+
+```text
+Primary goal:
+- Baseline the supported OOXML revision slice for insertions, deletions, and paragraph-mark changes.
+
+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 revisions sections of the local feature matrix research doc.
+
+Specific expectations:
+- preserve unsupported formatting and move revisions instead of flattening them
+- keep author/date metadata intact where present
+
+File ownership (only touch these paths):
+- src/io/ooxml/parse-revisions.ts
+- src/io/export/serialize-revisions.ts
+- src/io/ooxml/revision-boundaries.ts
+- test/io/revision-roundtrip.test.ts
+```
+
+## Agent A3: Review UI And Markup Modes
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 40
+
+### Context7
+
+- bundle: word-editor-ui
+- query: "clean/simple/all review displays, revision sidebars, and batch accept/reject surfaces"
+
+### Skills
+
+- role-implementation
+- domain-legal-review
+
+### Components
+
+- tracked-changes-and-review-actions
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- src/ui/review/markup-display-switch.tsx
+- src/ui/review/revision-sidebar.tsx
+- src/ui/review/accept-reject-actions.tsx
+- test/ui/revision-review-surface.test.tsx
+
+### Prompt
+
+```text
+Primary goal:
+- Expose redlines through review-first UI modes without turning the canvas into a diff wall.
+
+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:
+- simple and all modes must come from runtime truth
+- bulk accept/reject actions must route through the same review commands as single-item actions
+
+File ownership (only touch these paths):
+- src/ui/review/markup-display-switch.tsx
+- src/ui/review/revision-sidebar.tsx
+- src/ui/review/accept-reject-actions.tsx
+- test/ui/revision-review-surface.test.tsx
+```
+
+## Agent A4: Preservation Substrate
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 40
+
+### Context7
+
+- bundle: word-editor-ooxml
+- query: "opaque XML fragments, preserved package manifests, and locked-region editing behavior"
+
+### Skills
+
+- role-implementation
+- domain-docx-compatibility
+
+### Components
+
+- unsupported-ooxml-preservation
+
+### Exit contract
+
+- completion: integrated
+- durability: durable
+- proof: unit
+- doc-impact: owned
+
+### Deliverables
+
+- src/preservation/opaque-fragment-store.ts
+- src/preservation/preserved-part-manifest.ts
+- src/ui/editor-surface/locked-region.tsx
+- test/preservation/opaque-fragment-store.test.ts
+
+### Prompt
+
+```text
+Primary goal:
+- Land the preservation substrate that later waves will use to reattach unsupported OOXML safely.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/waves/specs/wave-1-ooxml-contracts.md.
+- Read the preserve-only sections of the local research docs.
+
+Specific expectations:
+- keep unsupported content atomic
+- keep delete behavior explicit and confirmable
+- do not yet claim malformed-doc handling or full package reattachment proof
+
+File ownership (only touch these paths):
+- src/preservation/opaque-fragment-store.ts
+- src/preservation/preserved-part-manifest.ts
+- src/ui/editor-surface/locked-region.tsx
+- test/preservation/opaque-fragment-store.test.ts
+```
+
+## Agent A5: Redline Baseline Proof
+
+### Executor
+
+- profile: proof-owner
+- retry-policy: sticky
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "revision fixture proof, accept/reject regression reporting, and mapping-aware review validation"
+
+### Skills
+
+- role-implementation
+- domain-docx-compatibility
+
+### Components
+
+- tracked-changes-and-review-actions
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- docs/plans/waves/reviews/wave-6-redline-proof.md
+- test/fixtures/docx/F11-redlines-basic.docx
+- test/fixtures/docx/F12-redlines-paragraph-joins-splits.docx
+- test/fixtures/docx/F14-revisions-in-tables-and-lists.docx
+
+### Proof artifacts
+
+- path: .tmp/wave-6-redlines/redline-roundtrip-report.json | kind: roundtrip-report | required-for: repo-landed
+- path: .tmp/wave-6-redlines/accept-reject-report.json | kind: action-report | required-for: repo-landed
+- path: .tmp/wave-6-redlines/revision-mapping-report.json | kind: remap-report | required-for: repo-landed
+
+### Prompt
+
+```text
+Primary goal:
+- Produce the bounded proof bundle for the supported redline slice, including source-backed paragraph-mark accept or reject and honest preserve-only reporting.
+
+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:
+- cover insertion, deletion, paragraph-mark edits, and source-backed accept/reject
+- record preserve-only structural revision cases rather than treating them as PASS
+- capture `S02` source-vs-export validator deltas and Word reopen notes as scenario evidence, not as replacement fixture proof
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-6-redline-proof.md
+- test/fixtures/docx/F11-redlines-basic.docx
+- test/fixtures/docx/F12-redlines-paragraph-joins-splits.docx
+- test/fixtures/docx/F14-revisions-in-tables-and-lists.docx
+- .tmp/wave-6-redlines/
+```