@beyondwork/docx-react-component 1.0.0 → 1.0.2

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

@@ -1,438 +0,0 @@
-# Wave 2 - Runtime Skeleton, Package Substrate, And Shell
-
-**Commit message**: `Build: land canonical runtime and editor shell substrate`
-
-## Component promotions
-
-- canonical-document-model: baseline-proved
-- command-and-transaction-runtime: baseline-proved
-- docx-import-and-normalization: baseline-proved
-- docx-export-and-serialization: baseline-proved
-- react-editor-ui: baseline-proved
-
-## Context7 defaults
-
-- bundle: word-editor-runtime
-- query: "ProseMirror state, transaction application, runtime orchestration, and React host integration for a schema-first editor"
-
-## Agent A0: cont-QA
-
-### Role prompts
-
-- docs/agents/wave-cont-qa-role.md
-
-### Executor
-
-- profile: deep-review
-
-### Context7
-
-- bundle: word-editor-testing
-- query: "repo-landed maturity checks, ownership boundaries, and deterministic unit-proof expectations"
-
-### Prompt
-
-```text
-Primary goal:
-- Refuse closure if Wave 2 claims more than a repo-landed substrate with deterministic tests.
-
-Required context before coding:
-- Read docs/reference/repository-guidance.md.
-- Read docs/research/agent-context-sources.md.
-- Read docs/reference/wave-planning-lessons.md.
-- Read docs/plans/master-plan.md, docs/plans/current-state.md, and docs/plans/component-cutover-matrix.json.
-- Read docs/plans/waves/wave-1.md.
-- Read docs/plans/waves/specs/wave-1-review-and-ui-contracts.md.
-
-Specific expectations:
-- fail if repo-landed claims depend on manual testing only
-- fail if the runtime and UI still bypass a single dispatch boundary
-- fail if the runtime-owned render contract drifts from the Wave 1 freeze
-- fail if the package IO layer rewrites unsupported parts by default
-
-File ownership (only touch these paths):
-- docs/plans/waves/reviews/wave-2-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 state, runtime, IO, and UI shell layers"
-
-### Prompt
-
-```text
-Primary goal:
-- Reconcile the landed substrate so later feature waves build on one runtime rather than parallel ad hoc shells.
-
-Required context before coding:
-- Read docs/reference/repository-guidance.md.
-- Read docs/research/agent-context-sources.md.
-- Read docs/reference/wave-planning-lessons.md.
-- Read docs/plans/master-plan.md, docs/plans/current-state.md, and docs/plans/waves/wave-1.md.
-- Read docs/plans/component-cutover-matrix.md and docs/plans/component-cutover-matrix.json.
-- Read docs/plans/waves/specs/wave-1-review-and-ui-contracts.md.
-
-Specific expectations:
-- call out any second source of truth for document state
-- call out any importer/exporter code path that bypasses canonical snapshots
-- treat RuntimeRenderSnapshot as the authoritative runtime/UI contract and treat narrower UI selectors as derived views, not a second runtime truth
-- reject closure if the public component shell and runtime event model diverge
-
-File ownership (only touch these paths):
-- .tmp/main-wave-launcher/integration/wave-2.md
-- .tmp/main-wave-launcher/integration/wave-2.json
-```
-
-## Agent A9: Documentation Steward
-
-### Role prompts
-
-- docs/agents/wave-documentation-role.md
-
-### Executor
-
-- profile: docs-pass
-
-### Context7
-
-- bundle: word-editor-contracts
-- query: "shared-plan updates for a repo-landed runtime, IO substrate, and editor shell"
-
-### Prompt
-
-```text
-Primary goal:
-- Update shared-plan docs to reflect the landed substrate and the exact proof gap that remains for baseline waves.
-
-Required context before coding:
-- Read docs/reference/repository-guidance.md.
-- Read docs/research/agent-context-sources.md.
-- Read docs/reference/wave-planning-lessons.md.
-- Read docs/plans/master-plan.md, docs/plans/current-state.md, docs/plans/migration.md, and docs/plans/component-cutover-matrix.md.
-- Read docs/plans/waves/wave-2.md.
-
-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: Canonical Model And Runtime Envelope
-
-### Executor
-
-- profile: implement-fast
-- budget.minutes: 45
-
-### Context7
-
-- bundle: word-editor-contracts
-- query: "strict TypeScript data models, canonical snapshots, and immutable document envelopes for structured editors"
-
-### Skills
-
-- role-implementation
-- domain-editor-architecture
-
-### Components
-
-- canonical-document-model
-- command-and-transaction-runtime
-
-### Exit contract
-
-- completion: integrated
-- durability: durable
-- proof: unit
-- doc-impact: owned
-
-### Deliverables
-
-- src/model/cds-1.0.0.ts
-- src/model/canonical-document.ts
-- src/model/snapshot.ts
-- test/model/canonical-document.test.ts
-
-### Prompt
-
-```text
-Primary goal:
-- Land the canonical document envelope and snapshot serialization substrate exactly as frozen in Wave 1.
-
-Required context before coding:
-- Read docs/reference/repository-guidance.md.
-- Read docs/research/agent-context-sources.md.
-- Read docs/reference/public-api.md.
-- Read docs/plans/waves/wave-1.md.
-- Read docs/plans/waves/specs/wave-1-runtime-contracts.md.
-
-Specific expectations:
-- keep snapshot serialization deterministic
-- validate schemaVersion and stable identifier domains
-- do not introduce view-state or DOM-derived fields into the canonical envelope
-
-File ownership (only touch these paths):
-- src/model/cds-1.0.0.ts
-- src/model/canonical-document.ts
-- src/model/snapshot.ts
-- test/model/canonical-document.test.ts
-```
-
-## Agent A2: Dispatch, Mapping, And Runtime Core
-
-### Executor
-
-- profile: implement-fast
-- budget.minutes: 45
-
-### Context7
-
-- bundle: word-editor-runtime
-- query: "editor state, transaction steps, mappings, selections, and runtime subscription models"
-
-### Skills
-
-- role-implementation
-- domain-editor-architecture
-
-### Components
-
-- command-and-transaction-runtime
-- canonical-document-model
-
-### Exit contract
-
-- completion: integrated
-- durability: durable
-- proof: unit
-- doc-impact: owned
-
-### Deliverables
-
-- src/core/state/editor-state.ts
-- src/core/commands/index.ts
-- src/core/selection/mapping.ts
-- src/runtime/document-runtime.ts
-- test/core/mapping.test.ts
-
-### Prompt
-
-```text
-Primary goal:
-- Land the command-dispatch and mapping substrate that every later editing feature will reuse.
-
-Required context before coding:
-- Read docs/reference/repository-guidance.md.
-- Read docs/research/agent-context-sources.md.
-- Read docs/plans/waves/specs/wave-1-component-boundaries.md.
-- Read docs/plans/waves/specs/wave-1-runtime-contracts.md.
-
-Specific expectations:
-- keep one dispatch path for all mutations
-- make mapping output explicit enough for comments, revisions, and opaque fragments to reuse later
-- expose subscriptions through runtime events rather than direct store mutation
-
-File ownership (only touch these paths):
-- src/core/state/editor-state.ts
-- src/core/commands/index.ts
-- src/core/selection/mapping.ts
-- src/runtime/document-runtime.ts
-- test/core/mapping.test.ts
-```
-
-## Agent A3: OPC And OOXML Substrate
-
-### Executor
-
-- profile: implement-fast
-- budget.minutes: 45
-
-### Context7
-
-- bundle: word-editor-ooxml
-- query: "OPC package manifests, content types, relationships, and document import/export session scaffolding"
-
-### Skills
-
-- role-implementation
-- domain-docx-compatibility
-
-### Components
-
-- docx-import-and-normalization
-- docx-export-and-serialization
-
-### Exit contract
-
-- completion: integrated
-- durability: durable
-- proof: unit
-- doc-impact: owned
-
-### Deliverables
-
-- src/io/opc/package-reader.ts
-- src/io/opc/package-writer.ts
-- src/io/ooxml/part-manifest.ts
-- src/io/export/export-session.ts
-- test/io/package-reader.test.ts
-
-### Prompt
-
-```text
-Primary goal:
-- Land the package-first document IO substrate without yet claiming feature-complete WordprocessingML 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 docs/plans/waves/specs/wave-1-ooxml-contracts.md.
-
-Specific expectations:
-- keep untouched parts and relationship manifests visible in the model
-- regenerate only editor-owned output paths
-- block any hidden normalization that would already lose unknown content
-
-File ownership (only touch these paths):
-- src/io/opc/package-reader.ts
-- src/io/opc/package-writer.ts
-- src/io/ooxml/part-manifest.ts
-- src/io/export/export-session.ts
-- test/io/package-reader.test.ts
-```
-
-## Agent A4: Public Component Shell
-
-### Executor
-
-- profile: implement-fast
-- budget.minutes: 45
-
-### Context7
-
-- bundle: word-editor-ui
-- query: "React refs, uncontrolled editors, shell composition, and compact document-surface-first UI layout"
-
-### Skills
-
-- role-implementation
-- domain-editor-architecture
-- domain-legal-review
-
-### Components
-
-- react-editor-ui
-- command-and-transaction-runtime
-
-### Exit contract
-
-- completion: integrated
-- durability: durable
-- proof: unit
-- doc-impact: owned
-
-### Deliverables
-
-- src/api/public-types.ts
-- src/ui/WordReviewEditor.tsx
-- src/ui/editor-surface/editor-surface.tsx
-- test/ui/word-review-editor.test.tsx
-
-### Prompt
-
-```text
-Primary goal:
-- Land the public React shell that binds to the runtime without making React the source of truth.
-
-Required context before coding:
-- Read DESIGN.md and docs/reference/repository-guidance.md.
-- Read docs/research/agent-context-sources.md.
-- Read docs/reference/public-api.md.
-- Read docs/plans/waves/specs/wave-1-review-and-ui-contracts.md.
-
-Specific expectations:
-- keep the canvas central and the chrome secondary
-- preserve the uncontrolled-by-default contract
-- expose imperative ref operations through the runtime, not direct view mutation
-
-File ownership (only touch these paths):
-- src/api/public-types.ts
-- src/ui/WordReviewEditor.tsx
-- src/ui/editor-surface/editor-surface.tsx
-- test/ui/word-review-editor.test.tsx
-```
-
-## Agent A5: Compatibility Report Skeleton
-
-### Executor
-
-- profile: implement-fast
-- budget.minutes: 35
-
-### Context7
-
-- bundle: word-editor-testing
-- query: "typed compatibility reports, fixture manifests, and unit-friendly validation surface design"
-
-### Skills
-
-- role-implementation
-- domain-docx-compatibility
-
-### Components
-
-- docx-import-and-normalization
-- docx-export-and-serialization
-
-### Exit contract
-
-- completion: contract
-- durability: durable
-- proof: unit
-- doc-impact: owned
-
-### Deliverables
-
-- src/validation/compatibility-report.ts
-- src/validation/diagnostics.ts
-- test/validation/compatibility-report.test.ts
-- test/fixtures/docx/fixtures.manifest.json
-
-### Prompt
-
-```text
-Primary goal:
-- Land the typed compatibility-report substrate and fixture manifest that later proof waves will extend.
-
-Required context before coding:
-- Read docs/reference/repository-guidance.md.
-- Read docs/research/agent-context-sources.md.
-- Read docs/reference/ooxml-compliance.md.
-- Read docs/research/docx-react-component/document_compatibility_and_testing_spec.md.
-
-Specific expectations:
-- keep feature classes explicit and closed
-- keep fixture metadata machine-readable
-- do not overclaim baseline validation before the proof artifacts exist
-
-File ownership (only touch these paths):
-- src/validation/compatibility-report.ts
-- src/validation/diagnostics.ts
-- test/validation/compatibility-report.test.ts
-- test/fixtures/docx/fixtures.manifest.json
-```