@beyondwork/docx-react-component 1.0.0 → 1.0.2

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

@@ -1,417 +0,0 @@
-# Wave 12 - Projection Fidelity, First-Class Tables, And AI Action Contract
-
-**Commit message**: `Build: land projection fidelity, tables, and AI contract`
-
-## Component promotions
-
-- canonical-document-model: fleet-ready
-- command-and-transaction-runtime: fleet-ready
-- comments-and-anchor-mapping: fleet-ready
-- tracked-changes-and-review-actions: fleet-ready
-- docx-import-and-normalization: fleet-ready
-- docx-export-and-serialization: fleet-ready
-- unsupported-ooxml-preservation: fleet-ready
-- compatibility-and-word-validation: fleet-ready
-- react-editor-ui: fleet-ready
-
-## Scope note
-
-Wave 12 starts the post-v1 legal-checklist sequence. It is a capability wave,
-not an automatic continuation of the bounded-v1 maturity staircase.
-
-The goal is to establish the new handling rule for the roadmap: high-value
-content should become `read-only projected` before it stays opaque by default,
-and supported slices should then move to bounded or full ownership.
-
-Tables remain the central owned slice in this wave, but Wave 12 also reserves
-the standard host-controlled AI action contract and keeps browser-font
-approximation honest through explicit trust surfaces.
-
-## Entry criteria
-
-- Wave 11 is closed or frozen enough that the bounded-v1 support boundary is
-  stable.
-- Shared docs already distinguish `read-only projected`, `opaque preserve-only`,
-  `policy locks`, and `compatibility-safety locks`.
-- The mounted shared workspace is the canonical frontend shell for new UX work.
-
-## Promotion conditions
-
-- cell-local edit, export, reload, validator, and Word reopen proof exist for
-  the supported table slice
-- compatibility output distinguishes supported table edits, read-only projected
-  structures, and opaque preserve-only behaviors
-- browser-font approximation never mutates exported OOXML font intent
-- `font_substitution` cues come from runtime truth instead of prototype-only
-  code
-- the AI action contract is reserved consistently across API/runtime/frontend
-  without implying direct model-to-DOM mutation or unreviewed drafting
-
-## Deliverables
-
-- typed table ownership and table-aware selection on the canonical runtime path
-- explicit projection rules for table-adjacent or still-unsupported structures
-  that can be shown safely before they are editable
-- package-backed import, export, reimport, validator, and Word proof for the
-  supported table slice
-- mounted table UI and trust surfaces for supported table editing, projected
-  table visibility, and font substitution
-- shared docs that keep the added projection, table, font, and AI-contract
-  slice bounded and explicit
-
-## Deploy environments
-
-- staging: railway-cli (shared workspace validation environment)
-
-## Context7 defaults
-
-- bundle: word-editor-ooxml
-- query: "projection fidelity, first-class tables, DOCX table import/export, Word reopen proof, browser font substitution, and AI action contract boundaries"
-
-## Agent A0: cont-QA
-
-### Role prompts
-
-- docs/agents/wave-cont-qa-role.md
-
-### Executor
-
-- profile: deep-review
-
-### Context7
-
-- bundle: word-editor-testing
-- query: "projection-first table slice closure, Word reopen proof, compatibility truth, browser-font approximation, and bounded AI contract claims"
-
-### Prompt
-
-```text
-Primary goal:
-- Refuse closure unless the repo has bounded, machine-visible proof for first-class tables and browser-font approximation.
-
-Required context before coding:
-- Read docs/reference/repository-guidance.md.
-- Read docs/research/agent-context-sources.md.
-- Read docs/reference/live-proof-waves.md.
-- Read docs/plans/current-state.md and docs/plans/waves/wave-12.md.
-
-Specific expectations:
-- block closure if supported table ownership is still indistinguishable from preserve-only package survival
-- block closure if the wave still treats preserve-only as a synonym for opaque locked rendering
-- block closure if font-substitution guidance silently mutates OOXML font intent or overclaims browser parity
-- block closure if the AI contract implies direct model-to-DOM edits or skips human confirmation
-- keep the Wave 12 slice explicit and bounded for later compare, semantics, and authoring work
-
-File ownership (only touch these paths):
-- docs/plans/waves/reviews/wave-12-cont-qa.md
-```
-
-## Agent A8: Integration Steward
-
-### Role prompts
-
-- docs/agents/wave-integration-role.md
-
-### Executor
-
-- profile: deep-review
-
-### Context7
-
-- bundle: word-editor-testing
-- query: "reconciling table runtime proof, projection behavior, compatibility evidence, font substitution, and bounded AI contract behavior"
-
-### Prompt
-
-```text
-Primary goal:
-- Decide whether the repo now owns a bounded first-class table slice without overclaiming beyond it.
-
-Required context before coding:
-- Read docs/reference/repository-guidance.md.
-- Read docs/research/agent-context-sources.md.
-- Read docs/reference/live-proof-waves.md.
-- Read docs/plans/master-plan.md, docs/plans/current-state.md, and docs/plans/waves/wave-12.md.
-
-Specific expectations:
-- block closure if table runtime, import/export, UI, and compatibility evidence disagree
-- block closure if the repo still treats supported cell edits like preserve-only structural survival
-- block closure if the repo cannot distinguish projected surfaces from opaque preserve-only surfaces
-- block closure if docs blur the Wave 12 slice with broader post-v1 compare, semantics, or autonomous AI work
-
-File ownership (only touch these paths):
-- .tmp/main-wave-launcher/integration/wave-12.md
-- .tmp/main-wave-launcher/integration/wave-12.json
-```
-
-## Agent A9: Documentation Steward
-
-### Role prompts
-
-- docs/agents/wave-documentation-role.md
-
-### Executor
-
-- profile: docs-pass
-
-### Context7
-
-- bundle: word-editor-contracts
-- query: "documenting projection fidelity, first-class tables, preserve-only boundaries, browser-font substitution, and the planned AI contract"
-
-### Prompt
-
-```text
-Primary goal:
-- Close the shared-plan docs around the Wave 12 projection, table, font, and AI-contract slice without implying broader legal-checklist ownership than the repo now has.
-
-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/reference/legal-checklist.md.
-- Read docs/plans/master-plan.md, docs/plans/current-state.md, and docs/plans/component-cutover-matrix.md.
-- Read the Wave 12 proof notes.
-
-File ownership (only touch these paths):
-- README.md
-- 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
-- docs/reference/ooxml-compliance.md
-- docs/reference/legal-checklist.md
-```
-
-## Agent A1: Table Model, Runtime, And DOCX Ownership
-
-### Executor
-
-- profile: proof-owner
-- retry-policy: sticky
-
-### Context7
-
-- bundle: word-editor-ooxml
-- query: "table nodes, selection, DOCX table parsing and serialization, validator-safe roundtrip behavior, and projected-vs-opaque handling boundaries"
-
-### Skills
-
-- role-implementation
-- domain-editor-architecture
-- domain-docx-compatibility
-
-### Components
-
-- canonical-document-model
-- command-and-transaction-runtime
-- docx-import-and-normalization
-- docx-export-and-serialization
-
-### Exit contract
-
-- completion: authoritative
-- durability: durable
-- proof: integration
-- doc-impact: owned
-
-### Deliverables
-
-- src/core/schema/table-schema.ts
-- src/core/selection/table-selection.ts
-- src/io/ooxml/parse-tables.ts
-- src/io/export/serialize-tables.ts
-- test/io/table-roundtrip.test.ts
-- docs/plans/waves/reviews/wave-12-table-runtime-proof.md
-
-### Proof artifacts
-
-- path: .tmp/wave-12-tables/table-runtime-roundtrip-report.json | kind: integration-report | required-for: baseline-proved
-- path: .tmp/wave-12-tables/table-session-edit-report.json | kind: integration-report | required-for: baseline-proved
-- path: .tmp/wave-12-tables/font-package-preservation-report.json | kind: validation-report | required-for: baseline-proved
-
-### Prompt
-
-```text
-Primary goal:
-- Move supported tables onto the canonical runtime path without damaging DOCX fidelity or Word reopen safety.
-
-Required context before coding:
-- Read docs/reference/repository-guidance.md.
-- Read docs/research/agent-context-sources.md.
-- Read docs/reference/ooxml-compliance.md.
-- Read test/fixtures/docx/README.md.
-
-Specific expectations:
-- own typed table structures instead of preserving the supported slice as opaque blocks
-- keep unsupported structural table behaviors explicit and non-destructive
-- prefer read-only projected rendering before opaque fallback whenever mapping is safe
-- never let browser-font approximation mutate exported OOXML font intent
-
-File ownership (only touch these paths):
-- src/core/schema/table-schema.ts
-- src/core/selection/table-selection.ts
-- src/io/ooxml/parse-tables.ts
-- src/io/export/serialize-tables.ts
-- test/io/table-roundtrip.test.ts
-- docs/plans/waves/reviews/wave-12-table-runtime-proof.md
-- .tmp/wave-12-tables/
-```
-
-## Agent A2: Table UI, Review Mapping, And Font/Projection Trust Surfaces
-
-### Executor
-
-- profile: implement-fast
-- budget.minutes: 50
-
-### Context7
-
-- bundle: word-editor-ui
-- query: "table editing UI, projected table visibility, comment and revision behavior in cells, and browser font-substitution diagnostics"
-
-### Skills
-
-- role-implementation
-- domain-legal-review
-- domain-docx-compatibility
-
-### Components
-
-- comments-and-anchor-mapping
-- tracked-changes-and-review-actions
-- unsupported-ooxml-preservation
-- compatibility-and-word-validation
-- react-editor-ui
-
-### Exit contract
-
-- completion: authoritative
-- durability: durable
-- proof: integration
-- doc-impact: owned
-
-### Deliverables
-
-- src/ui-tailwind/editor-surface/tw-table-view.tsx
-- src/ui-tailwind/review/tw-font-substitution-panel.tsx
-- src/review/store/comment-anchors.ts
-- test/ui/table-editor.test.tsx
-- docs/plans/waves/reviews/wave-12-table-ui-proof.md
-
-### Proof artifacts
-
-- path: .tmp/wave-12-tables/table-ui-interaction-report.json | kind: integration-report | required-for: baseline-proved
-- path: .tmp/wave-12-tables/table-compatibility-report.json | kind: compatibility-report | required-for: baseline-proved
-- path: .tmp/wave-12-tables/font-substitution-report.json | kind: compatibility-report | required-for: baseline-proved
-- path: .tmp/wave-12-tables/word-reopen-notes.md | kind: proof-note | required-for: baseline-proved
-
-### Prompt
-
-```text
-Primary goal:
-- Make the supported table slice visible and trustworthy in the shared workspace while keeping browser-font substitution and projected-structure behavior honest.
-
-Required context before coding:
-- Read docs/reference/repository-guidance.md.
-- Read docs/research/agent-context-sources.md.
-- Read DESIGN.md.
-- Read docs/legal-feedback-architecture.md.
-
-Specific expectations:
-- table UI must reflect supported cell-local editing, read-only projected structures, and preserve-only structural limits clearly
-- comments and supported insert/delete revisions in one cell should remain mappable through edits
-- `font_substitution` cues must describe runtime truth rather than approximating Word parity claims
-
-File ownership (only touch these paths):
-- src/ui-tailwind/editor-surface/tw-table-view.tsx
-- src/ui-tailwind/review/tw-font-substitution-panel.tsx
-- src/review/store/comment-anchors.ts
-- test/ui/table-editor.test.tsx
-- docs/plans/waves/reviews/wave-12-table-ui-proof.md
-- .tmp/wave-12-tables/
-```
-
-## Agent A3: API, Runtime, And Frontend AI Action Contract
-
-### Executor
-
-- profile: proof-owner
-- retry-policy: sticky
-
-### Context7
-
-- bundle: word-editor-contracts
-- query: "host-controlled AI action interface, runtime-mediated command application, review confirmation, validation/export workflows, and legal-editor action boundaries"
-
-### Skills
-
-- role-implementation
-- domain-editor-architecture
-- domain-legal-review
-
-### Components
-
-- command-and-transaction-runtime
-- compatibility-and-word-validation
-- react-editor-ui
-
-### Exit contract
-
-- completion: authoritative
-- durability: durable
-- proof: integration
-- doc-impact: owned
-
-### Deliverables
-
-- src/api/ai-actions.ts
-- src/runtime/ai-action-runtime.ts
-- src/ui-tailwind/toolbar/tw-ai-action-menu.tsx
-- test/runtime/ai-action-runtime.test.ts
-- docs/plans/waves/reviews/wave-12-ai-contract-proof.md
-
-### Proof artifacts
-
-- path: .tmp/wave-12-ai/ai-action-contract-report.json | kind: integration-report | required-for: baseline-proved
-- path: .tmp/wave-12-ai/ai-action-confirmation-report.json | kind: integration-report | required-for: baseline-proved
-- path: .tmp/wave-12-ai/ai-validate-export-report.json | kind: integration-report | required-for: baseline-proved
-
-### Prompt
-
-```text
-Primary goal:
-- Establish a host-controlled, runtime-mediated AI action contract that can support later drafting and review workflows without bypassing editor safety rules.
-
-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/reference/ooxml-compliance.md.
-
-Specific expectations:
-- host integrations provide model access; the editor does not ship a baked-in model client
-- the runtime packages canonical context such as selections, anchors, comments, revisions, and compatibility state
-- AI results must return proposals, bounded commands, or workflow intents rather than direct DOM mutation
-- content-changing application requires explicit review confirmation
-- validate/export workflows still go through normal runtime and compatibility gates
-
-File ownership (only touch these paths):
-- src/api/ai-actions.ts
-- src/runtime/ai-action-runtime.ts
-- src/ui-tailwind/toolbar/tw-ai-action-menu.tsx
-- test/runtime/ai-action-runtime.test.ts
-- docs/plans/waves/reviews/wave-12-ai-contract-proof.md
-- .tmp/wave-12-ai/
-```
-
-File ownership (only touch these paths):
-- src/ui-tailwind/editor-surface/tw-table-view.tsx
-- src/ui-tailwind/review/tw-font-substitution-panel.tsx
-- src/review/store/comment-anchors.ts
-- test/ui/table-editor.test.tsx
-- docs/plans/waves/reviews/wave-12-table-ui-proof.md
-- .tmp/wave-12-tables/
-```