@beyondwork/docx-react-component 1.0.0 → 1.0.2

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

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