@beyondwork/docx-react-component 1.0.0

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

@@ -0,0 +1,430 @@
+# Wave 4 - Architecture Completion And Runtime Truth
+
+**Commit message**: `Build: close live shell gaps and land preservation plus compatibility substrate`
+
+## Component promotions
+
+- comments-and-anchor-mapping: baseline-proved
+- unsupported-ooxml-preservation: baseline-proved
+- compatibility-and-word-validation: baseline-proved
+
+## Scope note
+
+This wave is replanned. The earlier structural-breadth outputs remain useful repo-landed substrate, but Wave 4 closure now centers on the live `WordReviewEditor` surface, runtime command wiring, the preservation subsystem, and the in-editor compatibility engine. Structural baseline proof for numbering, tables, media, and comment OOXML roundtrip moves into Wave 5.
+
+## Context7 defaults
+
+- bundle: word-editor-ooxml
+- query: "runtime-owned document surface editing, preservation locks, and compatibility derivation before structural breadth closure"
+
+## 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 for structural fixtures and honest repo-landed review substrate claims"
+
+### Prompt
+
+```text
+Primary goal:
+- Refuse closure if the live shell bypasses runtime truth or if shared docs still treat structural baseline proof as a Wave 4 requirement.
+
+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-3.md.
+- Read docs/research/docx-react-component/Feature Compatibility Matrix for a React Word Compatible Legal Editor v1.md.
+
+Specific expectations:
+- the live editor shell must stay runtime-owned rather than reconstructing document truth in React render
+- the structural fixture packet may remain carry-forward evidence for Wave 5 instead of a Wave 4 blocker
+- merged-cell handling must not be claimed editable beyond the stated support boundary
+- comment work in this wave is repo-landed only
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-4-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: "structural editing integration across numbering, tables, media, compatibility reports, and comment substrate"
+
+### Prompt
+
+```text
+Primary goal:
+- Reconcile the live editor shell, review projections, preservation substrate, and compatibility derivation into one clean architecture slice.
+
+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-4.md.
+
+Specific expectations:
+- block closure if any live editing path bypasses runtime commands or session truth
+- block closure if comment anchors are coupled to DOM ranges instead of runtime mappings
+- structural proof can remain carry-forward evidence for Wave 5 rather than a Wave 4 closure bar
+
+File ownership (only touch these paths):
+- .tmp/main-wave-launcher/integration/wave-4.md
+- .tmp/main-wave-launcher/integration/wave-4.json
+```
+
+## Agent A9: Documentation Steward
+
+### Role prompts
+
+- docs/agents/wave-documentation-role.md
+
+### Executor
+
+- profile: docs-pass
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "documenting structural slice support boundaries and proof surfaces"
+
+### Prompt
+
+```text
+Primary goal:
+- Keep shared-plan docs honest about Wave 4 closing as a repo-landed architecture slice while Wave 5 owns the structural and comment baseline proof.
+
+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 4 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: Numbering And List Semantics
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 45
+
+### Context7
+
+- bundle: word-editor-ooxml
+- query: "numbering.xml, list levels, numId/ilvl mapping, and restart behaviors in WordprocessingML"
+
+### Skills
+
+- role-implementation
+- domain-docx-compatibility
+
+### Components
+
+- unsupported-ooxml-preservation
+- compatibility-and-word-validation
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- src/io/ooxml/parse-numbering.ts
+- src/io/export/serialize-numbering.ts
+- src/core/commands/list-commands.ts
+- test/io/numbering-roundtrip.test.ts
+
+### Prompt
+
+```text
+Primary goal:
+- Land nested and restarted numbering on the existing runtime and IO substrate.
+
+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 numbering portions of docs/research/docx-react-component/Feature Compatibility Matrix for a React Word Compatible Legal Editor v1.md.
+
+Specific expectations:
+- preserve restart semantics
+- avoid HTML-list shortcuts that discard Word numbering identity
+
+File ownership (only touch these paths):
+- src/io/ooxml/parse-numbering.ts
+- src/io/export/serialize-numbering.ts
+- src/core/commands/list-commands.ts
+- test/io/numbering-roundtrip.test.ts
+```
+
+## Agent A2: Tables And Inline Media
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 45
+
+### Context7
+
+- bundle: word-editor-ooxml
+- query: "Word tables, merged cells, table grids, inline drawings, and media relationships"
+
+### Skills
+
+- role-implementation
+- domain-docx-compatibility
+
+### Components
+
+- compatibility-and-word-validation
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- src/io/ooxml/parse-tables.ts
+- src/io/export/serialize-tables.ts
+- src/io/ooxml/parse-inline-media.ts
+- test/io/table-media-roundtrip.test.ts
+
+### Prompt
+
+```text
+Primary goal:
+- Land tables with merged-cell preservation and inline-image round-trip support.
+
+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 tables and media sections of the local feature matrix research doc.
+
+Specific expectations:
+- keep merged-cell semantics preservable even when edit affordances stay narrow
+- preserve relationship integrity for media parts
+
+File ownership (only touch these paths):
+- src/io/ooxml/parse-tables.ts
+- src/io/export/serialize-tables.ts
+- src/io/ooxml/parse-inline-media.ts
+- test/io/table-media-roundtrip.test.ts
+```
+
+## Agent A3: Structural UI Surfaces
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 40
+
+### Context7
+
+- bundle: word-editor-ui
+- query: "table editing surfaces, list affordances, inline image placeholders, and calm review-first layout"
+
+### Skills
+
+- role-implementation
+- domain-legal-review
+
+### Components
+
+- compatibility-and-word-validation
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- src/ui/editor-surface/table-view.tsx
+- src/ui/editor-surface/list-view.tsx
+- src/ui/editor-surface/inline-image-view.tsx
+- test/ui/structural-surface.test.tsx
+
+### Prompt
+
+```text
+Primary goal:
+- Expose structural editing without turning the editor into a page-layout clone.
+
+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:
+- preserve the calm canvas posture
+- degrade rendering detail before data fidelity
+- keep merged cells safe even if some interactions stay locked or constrained
+
+File ownership (only touch these paths):
+- src/ui/editor-surface/table-view.tsx
+- src/ui/editor-surface/list-view.tsx
+- src/ui/editor-surface/inline-image-view.tsx
+- test/ui/structural-surface.test.tsx
+```
+
+## Agent A4: Comment Store Substrate
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 40
+
+### Context7
+
+- bundle: word-editor-runtime
+- query: "range mapping, comment-thread stores, anchor remapping, and detached review metadata"
+
+### Skills
+
+- role-implementation
+- domain-legal-review
+
+### Components
+
+- comments-and-anchor-mapping
+
+### Exit contract
+
+- completion: integrated
+- durability: durable
+- proof: unit
+- doc-impact: owned
+
+### Deliverables
+
+- src/review/store/comment-store.ts
+- src/review/store/comment-anchors.ts
+- src/ui/comments/comment-sidebar-shell.tsx
+- test/review/comment-store.test.ts
+
+### Prompt
+
+```text
+Primary goal:
+- Land the repo-level comment store and anchor substrate without yet claiming baseline proof for Word round-trip comments.
+
+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 comments sections of the local feature matrix research doc.
+
+Specific expectations:
+- keep comments outside the content tree
+- route all remapping through runtime mappings
+- keep thread state and resolution metadata typed and separate from UI state
+
+File ownership (only touch these paths):
+- src/review/store/comment-store.ts
+- src/review/store/comment-anchors.ts
+- src/ui/comments/comment-sidebar-shell.tsx
+- test/review/comment-store.test.ts
+```
+
+## Agent A5: Structural Proof Bundle
+
+### Executor
+
+- profile: proof-owner
+- retry-policy: sticky
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "fixture proof for numbering, tables, merged cells, images, and structural compatibility reports"
+
+### 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-4-structure-proof.md
+- test/fixtures/docx/F03-legal-outline-numbering.docx
+- test/fixtures/docx/F05-table-heavy-agreement.docx
+- test/fixtures/docx/F06-merged-cells-signature-table.docx
+- test/fixtures/docx/F07-inline-images-exhibit.docx
+
+### Proof artifacts
+
+- path: .tmp/wave-4-structure/structure-roundtrip-report.json | kind: roundtrip-report | required-for: repo-landed
+- path: .tmp/wave-4-structure/sdk-validation-report.json | kind: validation-report | required-for: repo-landed
+- path: .tmp/wave-4-structure/fixture-summary.md | kind: proof-note | required-for: repo-landed
+
+### Prompt
+
+```text
+Primary goal:
+- Produce the carry-forward structural fixture packet that Wave 5 will use to baseline the live path.
+
+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:
+- prove numbered lists, restart numbering, tables, merged cells, and inline images
+- record validator output and any preserve-only caveats explicitly
+- record any remaining gaps as carry-forward work instead of treating them as a Wave 4 closure blocker
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-4-structure-proof.md
+- test/fixtures/docx/F03-legal-outline-numbering.docx
+- test/fixtures/docx/F05-table-heavy-agreement.docx
+- test/fixtures/docx/F06-merged-cells-signature-table.docx
+- test/fixtures/docx/F07-inline-images-exhibit.docx
+- .tmp/wave-4-structure/
+```