@beyondwork/docx-react-component 1.0.0

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

@@ -0,0 +1,331 @@
+# Wave 17 - Advanced Review And Object Fidelity
+
+**Commit message**: `Build: complete advanced review and object fidelity`
+
+## Component promotions
+
+- 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
+
+- command-and-transaction-runtime: baseline-proved
+## Scope note
+
+Wave 17 continues Tier C closure by finishing the advanced review and legal
+object gaps that still sit between document-shell completeness and final parity.
+
+The goal is to make review behavior trustworthy across more than plain text:
+formatting revisions, move tracking, reviewer filtering, comments and revisions
+on cells and structural objects, and projected or partially editable legal
+objects such as images, shapes, and text boxes.
+
+This wave also extends the AI surface into richer review workflows such as
+comment triage, review summarization, and bounded object-level proposals, but
+only where canonical mapping and confirmation remain explicit.
+
+## Entry criteria
+
+- Wave 16 document-shell ownership and bounded shell projection are closed or
+  frozen enough that review anchors can cross mixed document surfaces safely.
+- Table, compare, semantics, and permission surfaces are stable enough to serve
+  as review targets without redefining their ownership models.
+- Shared docs already distinguish `bounded editable`, `read-only projected`,
+  and `opaque preserve-only` object behavior.
+
+## Promotion conditions
+
+- formatting revisions and move tracking are imported, rendered, edited or
+  actioned, exported, and reloaded with machine-visible proof
+- reviewer filtering and review-state completeness are grounded in runtime truth
+  rather than UI-only heuristics
+- comments and revisions on cells, shell surfaces, and non-text objects are
+  trustworthy on the declared slice
+- images, shapes, and text boxes have explicit projected or bounded-editable
+  behavior instead of generic placeholders
+- AI review workflows stay attached to mapped review objects and remain
+  proposal-first with explicit confirmation
+
+## Deliverables
+
+- advanced review contracts for formatting revisions, move tracking, reviewer
+  filters, and multi-surface review anchors
+- trustworthy projected or partially editable handling for images, shapes, and
+  text boxes on the declared legal-object slice
+- runtime and UI review workflows for richer multi-surface review behavior
+- bounded AI review operations for triage, summarization, and object-level
+  proposals
+- shared docs that keep advanced review distinct from final parity closure
+
+## Deploy environments
+
+- staging: railway-cli (shared workspace validation environment)
+
+## Context7 defaults
+
+- bundle: word-editor-ooxml
+- query: "formatting revisions, move tracking, reviewer filtering, comments on non-text objects, text boxes, shapes, images, and bounded AI review workflows"
+
+## Agent A0: cont-QA
+
+### Role prompts
+
+- docs/agents/wave-cont-qa-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "advanced review closure, object fidelity proof, and bounded AI review workflow claims"
+
+### Prompt
+
+```text
+Primary goal:
+- Refuse closure unless advanced review fidelity and legal-object handling both have bounded, machine-visible proof.
+
+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-17.md.
+
+Specific expectations:
+- block closure if formatting revisions or move tracking are still narrative rather than typed/testable
+- block closure if objects are still generic placeholders without explicit projection or edit boundaries
+- block closure if AI review workflows skip review confirmation or target unmappable surfaces
+- keep final checklist closure and low-priority Word surfaces explicitly deferred to Wave 18
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-17-cont-qa.md
+```
+
+## Agent A8: Integration Steward
+
+### Role prompts
+
+- docs/agents/wave-integration-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: word-editor-ooxml
+- query: "reconciling advanced review proof, legal-object projection, reviewer filtering, and AI review workflow behavior"
+
+### Prompt
+
+```text
+Primary goal:
+- Decide whether the repo now owns one coherent advanced-review and legal-object slice.
+
+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-17.md.
+
+Specific expectations:
+- block closure if review anchors, object rendering, and export behavior disagree
+- block closure if reviewer filtering or review completeness depends on UI-only state
+- block closure if AI review workflows exceed the surfaces the runtime can map explicitly
+- keep final parity proof and explicit low-priority Word handling deferred to Wave 18
+
+File ownership (only touch these paths):
+- .tmp/main-wave-launcher/integration/wave-17.md
+- .tmp/main-wave-launcher/integration/wave-17.json
+```
+
+## Agent A9: Documentation Steward
+
+### Role prompts
+
+- docs/agents/wave-documentation-role.md
+
+### Executor
+
+- profile: docs-pass
+
+### Context7
+
+- bundle: word-editor-contracts
+- query: "documenting advanced review fidelity, reviewer filtering, legal-object handling, and bounded AI review workflows"
+
+### Prompt
+
+```text
+Primary goal:
+- Close the shared-plan docs around the Wave 17 advanced-review and object-fidelity slice without implying final parity closure.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/reference/legal-checklist.md.
+- Read docs/plans/master-plan.md, docs/plans/current-state.md, docs/plans/migration.md, and docs/plans/component-cutover-matrix.md.
+- Read the Wave 17 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/legal-checklist.md
+```
+
+## Agent A1: Advanced Review Fidelity And Legal Objects
+
+### Executor
+
+- profile: proof-owner
+- retry-policy: sticky
+
+### Context7
+
+- bundle: word-editor-ooxml
+- query: "formatting revisions, move tracking, non-text review anchors, legal objects, text boxes, shapes, images, and Word-compatible object projection"
+
+### Skills
+
+- role-implementation
+- domain-editor-architecture
+- domain-docx-compatibility
+
+### Components
+
+- comments-and-anchor-mapping
+- tracked-changes-and-review-actions
+- docx-import-and-normalization
+- docx-export-and-serialization
+- unsupported-ooxml-preservation
+- react-editor-ui
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- src/review/advanced-review-model.ts
+- src/runtime/legal-objects-runtime.ts
+- src/ui-tailwind/review/tw-review-completeness-panel.tsx
+- test/review/advanced-review-model.test.ts
+- docs/plans/waves/reviews/wave-17-review-object-proof.md
+
+### Proof artifacts
+
+- path: .tmp/wave-17-advanced-review/formatting-revisions-report.json | kind: integration-report | required-for: fleet-ready
+- path: .tmp/wave-17-advanced-review/move-tracking-report.json | kind: integration-report | required-for: fleet-ready
+- path: .tmp/wave-17-advanced-review/object-anchor-report.json | kind: integration-report | required-for: fleet-ready
+- path: .tmp/wave-17-advanced-review/reviewer-filtering-report.json | kind: integration-report | required-for: fleet-ready
+- path: .tmp/wave-17-advanced-review/legal-objects-report.json | kind: integration-report | required-for: fleet-ready
+- path: .tmp/wave-17-advanced-review/word-reopen-notes.md | kind: proof-note | required-for: fleet-ready
+
+### Prompt
+
+```text
+Primary goal:
+- Make advanced review fidelity and legal-object handling trustworthy enough for legal review without pretending every Word object becomes fully editable.
+
+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.
+
+Specific expectations:
+- formatting revisions and move tracking must be typed, testable, and export-safe on the declared slice
+- comments and revisions on cells, shell surfaces, and supported objects must remain mappable through edits
+- objects should move to `read-only projected` or `bounded editable` before they stay opaque by default
+- keep OLE, macros, and final parity classification out of scope for this wave
+
+File ownership (only touch these paths):
+- src/review/advanced-review-model.ts
+- src/runtime/legal-objects-runtime.ts
+- src/ui-tailwind/review/tw-review-completeness-panel.tsx
+- test/review/advanced-review-model.test.ts
+- docs/plans/waves/reviews/wave-17-review-object-proof.md
+- .tmp/wave-17-advanced-review/
+```
+
+## Agent A2: AI Review Workflows And Object-Level Proposals
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 50
+
+### Context7
+
+- bundle: word-editor-contracts
+- query: "AI comment triage, review summarization, object-level edit proposals, reviewer filtering, and confirmation-safe legal review workflows"
+
+### 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/runtime/ai-review-workflows.ts
+- src/ui-tailwind/review/tw-ai-review-workflows-panel.tsx
+- test/runtime/ai-review-workflows.test.ts
+- docs/plans/waves/reviews/wave-17-ai-review-proof.md
+
+### Proof artifacts
+
+- path: .tmp/wave-17-advanced-review/ai-comment-triage-report.json | kind: integration-report | required-for: fleet-ready
+- path: .tmp/wave-17-advanced-review/ai-review-summary-report.json | kind: integration-report | required-for: fleet-ready
+- path: .tmp/wave-17-advanced-review/ai-object-proposal-report.json | kind: integration-report | required-for: fleet-ready
+
+### Prompt
+
+```text
+Primary goal:
+- Add richer AI review workflows for advanced review and object surfaces without losing runtime control or review safety.
+
+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-17.md.
+
+Specific expectations:
+- comment triage, review summaries, and object-level proposals must resolve against canonical review/object ids
+- outputs must remain proposal-first and explicitly confirmed
+- do not imply whole-document autonomous review closure or final legal-checklist completion in this wave
+
+File ownership (only touch these paths):
+- src/runtime/ai-review-workflows.ts
+- src/ui-tailwind/review/tw-ai-review-workflows-panel.tsx
+- test/runtime/ai-review-workflows.test.ts
+- docs/plans/waves/reviews/wave-17-ai-review-proof.md
+- .tmp/wave-17-advanced-review/
+```

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

@@ -0,0 +1,328 @@
+# Wave 18 - Parity And Legal Checklist Closure
+
+**Commit message**: `Build: close parity and legal-checklist coverage`
+
+## Component promotions
+
+- canonical-document-model: fleet-ready
+- command-and-transaction-runtime: 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 18 is the final parity-and-closure wave. It does not introduce a brand-new
+product tier; instead, it integrates, certifies, and classifies the accumulated
+post-v1 surface against `docs/reference/legal-checklist.md`.
+
+The goal is to make every remaining checklist item explicit as `owned`,
+`bounded editable`, `read-only projected`, `opaque preserve-only`, or
+intentionally deferred, while also closing the final AI contract boundaries and
+the low-priority Word-surface stance for embedded objects, OLE, and macros.
+
+## Entry criteria
+
+- Waves 12 through 17 are closed or frozen enough that one final integrated
+  proof line can operate on a stable post-v1 surface.
+- Shared docs already distinguish ownership state from rendering mode and keep
+  `policy locks` separate from `compatibility-safety locks`.
+- The legal-checklist coverage artifacts are current enough to support one final
+  repo-wide classification pass.
+
+## Promotion conditions
+
+- one integrated proof bundle exists across tables, compare, semantics,
+  structured authoring, document shell, advanced review, and legal objects
+- every `docs/reference/legal-checklist.md` item has an explicit final status
+- OLE, embedded objects, macros, and other low-priority Word surfaces have an
+  explicit handling stance instead of falling through ambiguity
+- the final AI contract states which actions are host-provided, runtime-native,
+  review-confirmed, blocked, or intentionally unsupported
+- roadmap, master plan, current-state, and coverage docs tell the same final
+  story without contradiction
+
+## Deliverables
+
+- one integrated parity proof bundle across the full post-v1 surface
+- final checklist coverage matrix with status per item
+- explicit low-priority Word-surface handling and compatibility-report stance
+- final AI capability and policy matrix
+- shared docs that close the roadmap honestly without overclaiming exact Word
+  parity or unsupported editing ownership
+
+## Deploy environments
+
+- staging: railway-cli (shared workspace validation environment)
+
+## Context7 defaults
+
+- bundle: word-editor-testing
+- query: "final legal-checklist coverage, integrated Word-compatible proof, embedded objects, OLE, macros, and AI contract closure"
+
+## Agent A0: cont-QA
+
+### Role prompts
+
+- docs/agents/wave-cont-qa-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "final parity closure, legal-checklist matrix, low-priority Word surface stance, and AI contract closure"
+
+### Prompt
+
+```text
+Primary goal:
+- Refuse closure unless the repo has a current, machine-visible integrated proof bundle and an honest final checklist matrix.
+
+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-18.md.
+
+Specific expectations:
+- block closure if any legal-checklist item still lacks an explicit final status
+- block closure if integrated proof quietly inherits stale evidence or contradictory statuses
+- block closure if low-priority Word surfaces or AI boundaries remain hand-wavy
+- keep exact Word pagination parity and unsupported feature ownership out of the success claim unless explicitly proved
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-18-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: "integrated post-v1 proof, legal-checklist coverage matrix, low-priority Word surface policy, and AI capability closure"
+
+### Prompt
+
+```text
+Primary goal:
+- Decide whether the repo now tells one coherent final story about ownership, projection, preservation, and intentional deferral.
+
+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-18.md.
+
+Specific expectations:
+- block closure if proof artifacts, roadmap docs, and checklist coverage disagree
+- block closure if low-priority Word surfaces have no explicit handling stance
+- block closure if AI capability claims exceed the runtime and policy model actually proved
+- keep exact Word parity and customer-product expansion out of scope unless explicitly certified
+
+File ownership (only touch these paths):
+- .tmp/main-wave-launcher/integration/wave-18.md
+- .tmp/main-wave-launcher/integration/wave-18.json
+```
+
+## Agent A9: Documentation Steward
+
+### Role prompts
+
+- docs/agents/wave-documentation-role.md
+
+### Executor
+
+- profile: docs-pass
+
+### Context7
+
+- bundle: word-editor-contracts
+- query: "final roadmap closure, legal-checklist coverage matrix, low-priority Word surface stance, and AI capability boundaries"
+
+### Prompt
+
+```text
+Primary goal:
+- Close the shared-plan docs around the final parity wave without hiding intentional deferrals or unsupported limits.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/reference/legal-checklist.md.
+- Read docs/plans/master-plan.md, docs/plans/current-state.md, docs/plans/migration.md, and docs/plans/component-cutover-matrix.md.
+- Read the Wave 18 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/legal-checklist.md
+- docs/plans/reference/legal-checklist-coverage.md
+```
+
+## Agent A1: Integrated Parity Proof And Checklist Matrix
+
+### Executor
+
+- profile: proof-owner
+- retry-policy: sticky
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "integrated post-v1 legal editor proof, checklist coverage mapping, validator evidence, Word reopen proof, and final status classification"
+
+### 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
+- compatibility-and-word-validation
+- react-editor-ui
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- docs/plans/reference/legal-checklist-coverage.md
+- docs/plans/waves/reviews/wave-18-parity-proof.md
+- .tmp/wave-18-parity/integrated-platform-report.json
+- .tmp/wave-18-parity/checklist-status-matrix.json
+- .tmp/wave-18-parity/validator-summary-report.json
+- .tmp/wave-18-parity/word-reopen-summary.md
+
+### Proof artifacts
+
+- path: .tmp/wave-18-parity/integrated-platform-report.json | kind: integration-report | required-for: fleet-ready
+- path: .tmp/wave-18-parity/checklist-status-matrix.json | kind: integration-report | required-for: fleet-ready
+- path: .tmp/wave-18-parity/validator-summary-report.json | kind: validation-report | required-for: fleet-ready
+- path: .tmp/wave-18-parity/word-reopen-summary.md | kind: proof-note | required-for: fleet-ready
+
+### Prompt
+
+```text
+Primary goal:
+- Produce one honest integrated proof bundle and final checklist matrix for the full post-v1 surface.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/reference/legal-checklist.md.
+- Read docs/reference/ooxml-compliance.md.
+
+Specific expectations:
+- every checklist item must end with an explicit final status
+- integrated proof must be fresh, replayable, and explicit about remaining non-goals
+- do not hide partial support behind generic "supported later" language
+
+File ownership (only touch these paths):
+- docs/plans/reference/legal-checklist-coverage.md
+- docs/plans/waves/reviews/wave-18-parity-proof.md
+- .tmp/wave-18-parity/integrated-platform-report.json
+- .tmp/wave-18-parity/checklist-status-matrix.json
+- .tmp/wave-18-parity/validator-summary-report.json
+- .tmp/wave-18-parity/word-reopen-summary.md
+```
+
+## Agent A2: Low-Priority Word Surfaces And AI Contract Closure
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 50
+
+### Context7
+
+- bundle: word-editor-contracts
+- query: "OLE, embedded objects, macros, explicit unsupported handling, AI capability matrix, confirmation policy, and legal editor action boundaries"
+
+### Skills
+
+- role-implementation
+- domain-editor-architecture
+- domain-docx-compatibility
+
+### Components
+
+- unsupported-ooxml-preservation
+- compatibility-and-word-validation
+- command-and-transaction-runtime
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- src/validation/low-priority-word-surfaces.ts
+- src/runtime/ai-action-policy.ts
+- test/validation/low-priority-word-surfaces.test.ts
+- docs/plans/waves/reviews/wave-18-ai-contract-closure.md
+- .tmp/wave-18-parity/low-priority-word-surfaces-report.json
+- .tmp/wave-18-parity/ai-capability-matrix.json
+- .tmp/wave-18-parity/ai-policy-summary.md
+
+### Proof artifacts
+
+- path: .tmp/wave-18-parity/low-priority-word-surfaces-report.json | kind: compatibility-report | required-for: fleet-ready
+- path: .tmp/wave-18-parity/ai-capability-matrix.json | kind: integration-report | required-for: fleet-ready
+- path: .tmp/wave-18-parity/ai-policy-summary.md | kind: proof-note | required-for: fleet-ready
+
+### Prompt
+
+```text
+Primary goal:
+- Close the final policy and support stance for low-priority Word surfaces and the AI action contract.
+
+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:
+- OLE, embedded objects, macros, and similar low-priority surfaces must have an explicit bounded stance
+- the AI contract must end with a clear matrix of allowed, confirmed, blocked, and unsupported actions
+- do not imply first-class editing ownership for surfaces that remain preserve-only or intentionally deferred
+
+File ownership (only touch these paths):
+- src/validation/low-priority-word-surfaces.ts
+- src/runtime/ai-action-policy.ts
+- test/validation/low-priority-word-surfaces.test.ts
+- docs/plans/waves/reviews/wave-18-ai-contract-closure.md
+- .tmp/wave-18-parity/low-priority-word-surfaces-report.json
+- .tmp/wave-18-parity/ai-capability-matrix.json
+- .tmp/wave-18-parity/ai-policy-summary.md
+```