@beyondwork/docx-react-component 1.0.0 → 1.0.2

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

@@ -1,526 +0,0 @@
-# Wave 7 - Preservation Proof, Package Fidelity, And Review Trust
-
-**Commit message**: `Build: baseline preserved parts, preserve-only fidelity, and review trust`
-
-## Component promotions
-
-- unsupported-ooxml-preservation: baseline-proved
-- tracked-changes-and-review-actions: baseline-proved
-
-## Scope note
-
-Wave 7 closes the remaining preserve-only package backbone after the imported-redline freeform export block was removed on the canonical export path. It is the wave where preserve-only behavior must become explicit across the full Wave 7 fixture set, including package parts, note parts, fields, custom XML, unknown OOXML, malformed packages, and imported review markup that the editor does not safely own.
-
-This wave also closes the bounded tracked-change baseline gate that Wave 6 intentionally left open. The goal is not broader feature expansion. The goal is to prove that the supported tracked-change slice and the preserve-only review slice now coexist without silent loss, destructive downgrade, or misleading export claims.
-
-## Entry criteria
-
-- Wave 6 proof artifacts and review notes are current.
-- `docs/plans/current-state.md` and `docs/roadmap.md` still describe imported redline export as `repo-landed`, not fully certified.
-- The Wave 7-owned fixture registry in `test/fixtures/docx/README.md` is aligned to `F15` through `F21`.
-- Wave 8 work must not start until the Wave 7 proof bundle, trust note, and integration summary all exist and agree.
-
-## Promotion conditions
-
-- `F15` through `F21` are explicitly covered with machine-visible proof and matching notes.
-- preserve-only comment and revision markup inside opaque or locked content cannot silently disappear during export
-- preserved parts, relationships, and content-type declarations survive reattachment with explicit reporting
-- malformed packages stay fail-closed in diagnostics or read-only mode with export blocked
-- the supported tracked-change slice is baseline-proved at the preserve-only boundary rather than jumping from `repo-landed` to live-pilot claims later
-
-## Context7 defaults
-
-- bundle: word-editor-ooxml
-- query: "package preservation, preserved parts, preserve-only package fidelity, imported review markup, and malformed package diagnostics"
-
-## Agent A0: cont-QA
-
-### Role prompts
-
-- docs/agents/wave-cont-qa-role.md
-
-### Executor
-
-- profile: deep-review
-
-### Context7
-
-- bundle: word-editor-testing
-- query: "preserved-part proof completeness, preserve-only package fidelity, tracked-change boundary discipline, and malformed-doc closure"
-
-### Prompt
-
-```text
-Primary goal:
-- Refuse closure unless preserved-part fidelity, preserve-only review fidelity, and the tracked-change baseline gate are all backed by explicit evidence.
-
-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-6.md.
-- Read the preservation, revisions, and malformed-doc sections of the local research docs.
-
-Specific expectations:
-- preserve-only must stay machine-visible proof, not a narrative promise
-- supported imported redline export must remain non-destructive while preserve-only review cases stay explicit
-- malformed docs must stay fail-closed into diagnostics or read-only mode
-- block closure if the tracked-change maturity line still overclaims beyond the committed proof
-
-File ownership (only touch these paths):
-- docs/plans/waves/reviews/wave-7-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: "reattachment integrity, preserved-part reporting, tracked-change boundary proof, preserve-only package fidelity, and diagnostics mode"
-
-### Prompt
-
-```text
-Primary goal:
-- Reconcile preserved-part reporting, export reattachment, tracked-change boundary proof, preserve-only package fidelity, and diagnostics evidence into one baseline claim.
-
-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-7.md.
-
-Specific expectations:
-- block closure if preserved fragments can silently disappear
-- block closure if preserve-only imported comment or revision markup is still stripped or rewritten destructively
-- block closure if tracked-change proof still depends on a weaker maturity line than the shared docs imply
-- block closure if read-only diagnostics mode still allows destructive export
-
-File ownership (only touch these paths):
-- .tmp/main-wave-launcher/integration/wave-7.md
-- .tmp/main-wave-launcher/integration/wave-7.json
-```
-
-## Agent A9: Documentation Steward
-
-### Role prompts
-
-- docs/agents/wave-documentation-role.md
-
-### Executor
-
-- profile: docs-pass
-
-### Context7
-
-- bundle: word-editor-testing
-- query: "documenting preserve-only guarantees, tracked-change baseline proof, package fidelity, and diagnostics-mode behavior"
-
-### Prompt
-
-```text
-Primary goal:
-- Update shared-plan docs to make preserved-part guarantees, tracked-change baseline closure, canonical export boundaries, and diagnostics-mode behavior explicit.
-
-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 7 proof notes.
-
-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: Package Preservation And Reattachment
-
-### Executor
-
-- profile: implement-fast
-- budget.minutes: 45
-
-### Context7
-
-- bundle: word-editor-ooxml
-- query: "package parts, relationship manifests, content types, note parts, and safe reattachment of preserved OOXML"
-
-### Skills
-
-- role-implementation
-- domain-docx-compatibility
-
-### Components
-
-- unsupported-ooxml-preservation
-
-### Exit contract
-
-- completion: authoritative
-- durability: durable
-- proof: integration
-- doc-impact: owned
-
-### Deliverables
-
-- src/preservation/package-preservation.ts
-- src/io/export/reattach-preserved-parts.ts
-- src/io/export/export-session.ts
-- src/preservation/markup-compatibility.ts
-- test/preservation/package-preservation.test.ts
-
-### Prompt
-
-```text
-Primary goal:
-- Make preservation concrete at the package graph level, including relationships, content types, note parts, and safe export behavior around preserve-only package surfaces.
-
-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 preservation sections of the local research docs.
-
-Specific expectations:
-- preserve unknown parts and relationships unless the editor explicitly owns them
-- preserve footnote, endnote, field, and custom XML package surfaces without inventing semantic rewrites
-- keep canonical imported-redline export non-destructive while preserve-only package regions remain explicit
-- keep AlternateContent and mc:Ignorable branches intact
-
-File ownership (only touch these paths):
-- src/preservation/package-preservation.ts
-- src/io/export/reattach-preserved-parts.ts
-- src/io/export/export-session.ts
-- src/preservation/markup-compatibility.ts
-- test/preservation/package-preservation.test.ts
-```
-
-## Agent A2: Opaque Regions, Locked Editing, And Trust Messaging
-
-### Executor
-
-- profile: implement-fast
-- budget.minutes: 40
-
-### Context7
-
-- bundle: word-editor-ui
-- query: "locked regions, opaque placeholders, preserve-only warnings, and trustworthy user-facing review messaging"
-
-### Skills
-
-- role-implementation
-- domain-docx-compatibility
-- domain-legal-review
-
-### Components
-
-- unsupported-ooxml-preservation
-
-### Exit contract
-
-- completion: authoritative
-- durability: durable
-- proof: integration
-- doc-impact: owned
-
-### Deliverables
-
-- src/preservation/opaque-region.ts
-- src/ui/compatibility/locked-region-panel.tsx
-- src/ui/compatibility/compatibility-panel.tsx
-- src/ui/editor-surface/opaque-region-view.tsx
-- src/ui/editor-surface/editor-surface.tsx
-- src/ui/status/status-bar.tsx
-- test/ui/opaque-region.test.tsx
-- test/ui/core-text-editor.test.tsx
-- test/ui/word-review-editor.interaction.test.tsx
-
-### Prompt
-
-```text
-Primary goal:
-- Expose preserve-only content as locked, precise, non-destructive UI surfaces with trustworthy warnings and export-block messaging.
-
-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:
-- warnings must be specific and actionable
-- deleting opaque regions must be explicit rather than incidental
-- diagnostics/read-only mode must explain why export is blocked without overstating unsupported-fatal scope
-- preserve-only review markup must be understandable without visually overwhelming the document surface
-- mount the preserve-only trust surfaces in the shipped editor path; isolated helper coverage is not enough for Wave 7 closure
-- render concrete `blockExportReasons` in the mounted compatibility UI and keep the status bar from claiming `Compatibility: Clear` while export is blocked by diagnostics mode
-
-File ownership (only touch these paths):
-- src/preservation/opaque-region.ts
-- src/ui/compatibility/locked-region-panel.tsx
-- src/ui/compatibility/compatibility-panel.tsx
-- src/ui/editor-surface/opaque-region-view.tsx
-- src/ui/editor-surface/editor-surface.tsx
-- src/ui/status/status-bar.tsx
-- test/ui/opaque-region.test.tsx
-- test/ui/core-text-editor.test.tsx
-- test/ui/word-review-editor.interaction.test.tsx
-```
-
-## Agent A3: Diagnostics And Corrupt Package Handling
-
-### Executor
-
-- profile: implement-fast
-- budget.minutes: 40
-
-### Context7
-
-- bundle: word-editor-ooxml
-- query: "ZIP integrity checks, broken relationship graphs, malformed XML, and read-only diagnostics for unsupported-fatal documents"
-
-### Skills
-
-- role-implementation
-- domain-docx-compatibility
-
-### Components
-
-- unsupported-ooxml-preservation
-
-### Exit contract
-
-- completion: authoritative
-- durability: durable
-- proof: integration
-- doc-impact: owned
-
-### Deliverables
-
-- src/io/opc/corrupt-package.ts
-- src/validation/import-diagnostics.ts
-- src/runtime/read-only-diagnostics-runtime.ts
-- src/io/docx-session.ts
-- test/validation/malformed-doc.test.ts
-- test/io/docx-session.test.ts
-
-### Prompt
-
-```text
-Primary goal:
-- Fail closed on malformed documents while still giving the operator useful diagnostics and keeping package failures distinct from later validation failures.
-
-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 malformed-document sections of the local research docs.
-
-Specific expectations:
-- no destructive export in diagnostics mode
-- package failures and SDK failures must stay distinguishable
-- read-only diagnostics must preserve the import truth instead of pretending the document is partially editable
-- adopt the shared diagnostics helpers on the live `loadDocxEditorSession` path; helper-only proof is not enough for Wave 7 closure
-- keep malformed-package intake and validation-failure intake on a single conservative diagnostics contract without fabricating editability
-
-File ownership (only touch these paths):
-- src/io/opc/corrupt-package.ts
-- src/validation/import-diagnostics.ts
-- src/runtime/read-only-diagnostics-runtime.ts
-- src/io/docx-session.ts
-- test/validation/malformed-doc.test.ts
-- test/io/docx-session.test.ts
-```
-
-## Agent A4: Preservation And Tracked-Change Baseline Proof
-
-### Executor
-
-- profile: proof-owner
-- retry-policy: sticky
-
-### Context7
-
-- bundle: word-editor-testing
-- query: "preservation fixtures, tracked-change boundary proof, preserved-part reporting, package fidelity, and malformed-doc diagnostics evidence"
-
-### Skills
-
-- role-implementation
-- domain-docx-compatibility
-
-### Components
-
-- unsupported-ooxml-preservation
-- tracked-changes-and-review-actions
-
-### Exit contract
-
-- completion: authoritative
-- durability: durable
-- proof: integration
-- doc-impact: owned
-
-### Deliverables
-
-- docs/plans/waves/reviews/wave-7-preservation-proof.md
-- test/fixtures/docx/F15-sections-headers-footers.docx
-- test/fixtures/docx/F16-footnotes-endnotes.docx
-- test/fixtures/docx/F17-fields-and-toc.docx
-- test/fixtures/docx/F18-content-controls-template.docx
-- test/fixtures/docx/F19-custom-xml-doc-assembly.docx
-- test/fixtures/docx/F20-unknown-ooxml-and-alternatecontent.docx
-- test/fixtures/docx/F21-malformed-broken-docx.docx
-
-### Proof artifacts
-
-- path: .tmp/wave-7-preservation/preservation-manifest.json | kind: manifest | required-for: baseline-proved
-- path: .tmp/wave-7-preservation/reattachment-report.json | kind: roundtrip-report | required-for: baseline-proved
-- path: .tmp/wave-7-preservation/package-fidelity-report.json | kind: action-report | required-for: baseline-proved
-- path: .tmp/wave-7-preservation/review-boundary-report.json | kind: integration-report | required-for: baseline-proved
-- path: .tmp/wave-7-preservation/malformed-doc-report.json | kind: diagnostics-report | required-for: baseline-proved
-
-### Prompt
-
-```text
-Primary goal:
-- Produce the bounded proof bundle for preserve-only behavior, tracked-change boundary safety, preserved-part reporting, package fidelity, and malformed-doc handling.
-
-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:
-- prove preservation for sections, headers, notes, fields, SDTs, custom XML, and AlternateContent
-- prove canonical imported-redline export remains safe while preserve-only package and review cases stay explicit
-- prove preserve-only imported comment and revision markup are not silently stripped
-- prove diagnostics/read-only handling for malformed packages
-- record any user-visible lock or warning behavior explicitly
-
-File ownership (only touch these paths):
-- docs/plans/waves/reviews/wave-7-preservation-proof.md
-- test/fixtures/docx/F15-sections-headers-footers.docx
-- test/fixtures/docx/F16-footnotes-endnotes.docx
-- test/fixtures/docx/F17-fields-and-toc.docx
-- test/fixtures/docx/F18-content-controls-template.docx
-- test/fixtures/docx/F19-custom-xml-doc-assembly.docx
-- test/fixtures/docx/F20-unknown-ooxml-and-alternatecontent.docx
-- test/fixtures/docx/F21-malformed-broken-docx.docx
-- .tmp/wave-7-preservation/
-```
-
-## Agent A5: OOXML Preservation Compliance Review
-
-### Role prompts
-
-- docs/agents/wave-cont-qa-role.md
-
-### Executor
-
-- profile: deep-review
-
-### Context7
-
-- bundle: word-editor-ooxml
-- query: "unknown parts, relationship retention, AlternateContent, preserve-only review markup, and non-destructive OOXML export boundaries"
-
-### Components
-
-- unsupported-ooxml-preservation
-- tracked-changes-and-review-actions
-
-### Exit contract
-
-- completion: integrated
-- durability: durable
-- proof: integration
-- doc-impact: owned
-
-### Prompt
-
-```text
-Primary goal:
-- Review the Wave 7 output as an OOXML and package-fidelity slice rather than only a test slice.
-
-Required context before coding:
-- Read docs/reference/ooxml-compliance.md.
-- Read docs/reference/repository-guidance.md.
-- Read docs/research/agent-context-sources.md.
-- Read docs/plans/waves/wave-7.md and the preservation proof note.
-
-Specific expectations:
-- block closure if unknown relationships or package parts can disappear without an explicit compatibility story
-- block closure if AlternateContent, mc:Ignorable, note parts, field markup, or custom XML wrappers are overclaimed
-- block closure if preserve-only review markup still depends on regex-style stripping or narrative exceptions
-
-File ownership (only touch these paths):
-- docs/plans/waves/reviews/wave-7-ooxml-compliance.md
-```
-
-## Agent A6: Preserve-Only Trust And Warning UX Pass
-
-### Executor
-
-- profile: proof-owner
-- retry-policy: sticky
-
-### Context7
-
-- bundle: word-editor-ui
-- query: "user trust around locked regions, export blocking, diagnostics mode, and preserve-only warning comprehension"
-
-### Components
-
-- unsupported-ooxml-preservation
-
-### Exit contract
-
-- completion: authoritative
-- durability: durable
-- proof: integration
-- doc-impact: owned
-
-### Deliverables
-
-- docs/plans/waves/reviews/wave-7-trust-ux.md
-
-### Proof artifacts
-
-- path: .tmp/wave-7-preservation/trust-ux-checklist.md | kind: proof-note | required-for: baseline-proved
-- path: .tmp/wave-7-preservation/locked-region-ui-smoke.json | kind: integration-report | required-for: baseline-proved
-
-### Prompt
-
-```text
-Primary goal:
-- Prove that preserve-only and diagnostics behavior is understandable, explicit, and calm enough for legal-review workflows.
-
-Required context before coding:
-- Read DESIGN.md.
-- Read docs/reference/repository-guidance.md.
-- Read docs/research/agent-context-sources.md.
-- Read docs/plans/waves/wave-7.md.
-- Read the locked-region and diagnostics UI surfaces in source and proof notes.
-
-Specific expectations:
-- verify that locked content, preserve-only warnings, blocked export, and diagnostics mode answer "what happened, what is safe, and what can I do next?"
-- record misunderstandings or ambiguity as blocking issues, not polish notes
-- keep the document surface central and warning chrome secondary
-
-File ownership (only touch these paths):
-- docs/plans/waves/reviews/wave-7-trust-ux.md
-- .tmp/wave-7-preservation/
-```