@beyondwork/docx-react-component 1.0.0

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

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