@beyondwork/docx-react-component 1.0.0

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

@@ -0,0 +1,670 @@
+# Wave 10 - QA-Proved V1 Certification
+
+**Commit message**: `Build: qa-prove the v1 editor and internal services`
+
+## Component promotions
+
+- canonical-document-model: qa-proved
+- command-and-transaction-runtime: qa-proved
+- comments-and-anchor-mapping: qa-proved
+- tracked-changes-and-review-actions: qa-proved
+- docx-import-and-normalization: qa-proved
+- docx-export-and-serialization: qa-proved
+- unsupported-ooxml-preservation: qa-proved
+- compatibility-and-word-validation: qa-proved
+- react-editor-ui: qa-proved
+- railway-test-harness: qa-proved
+- openxml-sdk-validator-service: qa-proved
+
+## Scope note
+
+Wave 10 is the final internal QA-certification wave for the declared v1 surface. It must turn the frozen fixture corpus, representative scenarios, validator evidence, manual Word observations, accessibility and design signoff, and performance budgets into one fresh certification bundle.
+
+`qa-proved` is still not the same as release-ready packaging. That belongs to the next wave. Wave 10 proves that the declared v1 product is internally certified, honestly documented, and backed by current machine-visible evidence.
+
+Wave 10 must also preserve an honest handoff into the deferred legal-fidelity
+packet. Final QA surfaces, docs, and trust messaging should not encode
+paragraph-only assumptions or fake browser-font parity in ways that would
+undercut later first-class tables and curated-font approximation work.
+
+## Entry criteria
+
+- Wave 9 live proof, reviewer-task matrix, performance smoke, and manual-certification capture are current.
+- Shared docs still distinguish `qa-proved` from later `fleet-ready` or release-oriented work.
+- The release-gate fixture registry in `test/fixtures/docx/README.md` is current and unchanged unless an explicit contract revision landed first.
+
+## Promotion conditions
+
+- every promoted component has fresh Wave 10 QA evidence, not only older pilot artifacts
+- the certification matrix explicitly covers `F01` through `F21` plus `S01` and `S02`
+- accessibility, DESIGN.md conformance, and performance budgets all have explicit signoff artifacts
+- the final docs do not overclaim support boundaries, scenario evidence, or Word certification depth
+- representative scenario artifacts remain outside the frozen release-gate set while still appearing in the final QA bundle
+
+## Current workspace review rule
+
+Wave 10 is the final QA-certification wave for the declared v1 surface. Any
+design-conformance, accessibility, or release-surface UX signoff in this wave
+must review the current runtime-backed shared workspace so the final QA bundle
+judges the real shipped shell against the intended future product direction.
+
+Required review inputs for design-facing work:
+
+- `docs/legal-feedback-architecture.md`
+- `docs/reference/prototype-agent-prompt-legal-fidelity.md`
+- `docs/reference/word-review-editor-ux-guide.md`
+- `docs/plans/waves/deferred/legal-feedback-wave-expansion.md`
+- `services/react-word-editor/app/demo/page.tsx`
+- `services/react-word-editor/components/harness-workspace-page.tsx`
+- `services/react-word-editor/components/harness-editor-session-client.tsx`
+- `src/ui/WordReviewEditor.tsx`
+- `src/ui-tailwind/tw-review-workspace.tsx`
+- `src/ui-tailwind/review/tw-review-rail.tsx`
+- `src/ui-tailwind/toolbar/tw-toolbar.tsx`
+- `services/react-word-editor/lib/demo-fixtures.ts`
+
+This review does not authorize widening the Wave 10 support boundary. It is
+meant to catch drift, misleading visual claims, and contradictions with the
+future demo or trust posture on the current mounted shell.
+
+## Certification matrix
+
+- automated regression coverage:
+  `F01` through `F21` must all run through the same harness-controlled artifact pipeline with explicit pass, block, or preserve-only expectations
+- manual Word desktop and Word web coverage:
+  at minimum `F01`, `F03`, `F05`, `F09`, `F11`, `F12`, `F15`, `F20`, and `S01` must have fresh reopen notes tied to concrete run ids
+- preserve-only fixture judgment:
+  preserve-only fixtures pass only when survival, locking, warning, and non-destructive export behavior match the declared contract; they are not judged by the same semantic-edit criteria as supported-roundtrip fixtures
+- unsupported-fatal fixture judgment:
+  `F21` passes only when import fails closed and export remains blocked
+
+## Deploy environments
+
+- staging: railway-cli (internal Railway validation environment)
+
+## Context7 defaults
+
+- bundle: word-editor-testing
+- query: "fixture certification, Word reopen proof, validator evidence, accessibility, performance, and final QA closure for a Word-compatible editor"
+
+## Agent A0: cont-QA
+
+### Role prompts
+
+- docs/agents/wave-cont-qa-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "qa-proof closure, regression completeness, accessibility and performance signoff, and final compatibility evidence"
+
+### Prompt
+
+```text
+Primary goal:
+- Refuse closure unless the repo has full QA evidence for the declared v1 surface and the proof bundle is current.
+
+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-9.md.
+
+Specific expectations:
+- all promoted components need explicit regression, certification, accessibility, or performance evidence
+- stale pilot artifacts are not enough for qa-proved
+- representative scenario artifacts must appear in the certification bundle even though they are not release-gate fixtures
+- block closure if any signoff surface still depends on narrative confidence instead of current artifacts
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-10-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 regression reports, certification notes, validator results, accessibility signoff, and shared-plan closure"
+
+### Prompt
+
+```text
+Primary goal:
+- Decide whether the editor and internal services are genuinely qa-proved for the v1 contract.
+
+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-10.md.
+
+Specific expectations:
+- block closure if any promoted component lacks a clear QA artifact
+- block closure if release docs still imply weaker or different support boundaries
+- block closure if accessibility, design-conformance, or performance signoff disagree with the product claims
+
+File ownership (only touch these paths):
+- .tmp/main-wave-launcher/integration/wave-10.md
+- .tmp/main-wave-launcher/integration/wave-10.json
+```
+
+## Agent A9: Documentation Steward
+
+### Role prompts
+
+- docs/agents/wave-documentation-role.md
+
+### Executor
+
+- profile: docs-pass
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "documenting the final v1 support boundary, certification evidence, remaining exclusions, and the handoff to release readiness"
+
+### Prompt
+
+```text
+Primary goal:
+- Close the shared-plan and operator docs around the qa-proved v1 definition without smuggling in later release-readiness claims.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/legal-feedback-architecture.md.
+- Read docs/plans/waves/deferred/legal-feedback-wave-expansion.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 10 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
+```
+
+## Agent A1: Regression Suite And Release Gates
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 45
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "fixture manifests, integration regression reports, release-gate matrices, and certification freshness"
+
+### Skills
+
+- role-implementation
+- domain-docx-compatibility
+
+### Components
+
+- compatibility-and-word-validation
+- railway-test-harness
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- services/react-word-editor/app/api/fixtures/[fixtureId]/run/route.ts
+- services/react-word-editor/lib/regression-report.ts
+- test/fixtures/docx/certification-manifest.json
+- docs/plans/waves/reviews/wave-10-regression-proof.md
+
+### Proof artifacts
+
+- path: .tmp/wave-10-certification/regression-report.json | kind: integration-report | required-for: qa-proved
+- path: .tmp/wave-10-certification/fixture-coverage.json | kind: manifest | required-for: qa-proved
+- path: .tmp/wave-10-certification/certification-freshness.json | kind: manifest | required-for: qa-proved
+
+### Prompt
+
+```text
+Primary goal:
+- Make the regression suite and release gates explicit and machine-visible for the entire declared v1 fixture set.
+
+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:
+- all supported-roundtrip fixtures must be runnable through one harness path
+- the certification manifest must name the exact release-gate fixtures and the required manual-review subset
+- keep `S01` and `S02` out of the frozen release-gate list while still surfacing them as representative certification scenarios
+- freshness data must make it impossible for stale pilot runs to satisfy Wave 10 closure
+
+File ownership (only touch these paths):
+- services/react-word-editor/app/api/fixtures/[fixtureId]/run/route.ts
+- services/react-word-editor/lib/regression-report.ts
+- test/fixtures/docx/certification-manifest.json
+- docs/plans/waves/reviews/wave-10-regression-proof.md
+- .tmp/wave-10-certification/
+```
+
+## Agent A2: Word Desktop And Web Certification Bundle
+
+### Executor
+
+- profile: proof-owner
+- retry-policy: sticky
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "structured certification capture, artifact attachment, preserve-only judgment, and final compatibility proof bundling"
+
+### Skills
+
+- role-infra
+- role-deploy
+- provider-railway
+
+### Components
+
+- canonical-document-model
+- command-and-transaction-runtime
+- comments-and-anchor-mapping
+- tracked-changes-and-review-actions
+- docx-import-and-normalization
+- docx-export-and-serialization
+- unsupported-ooxml-preservation
+- compatibility-and-word-validation
+- react-editor-ui
+- railway-test-harness
+
+### Exit contract
+
+- completion: live
+- durability: durable
+- proof: live
+- doc-impact: owned
+
+### Deliverables
+
+- docs/plans/operations/wave-10-word-certification.md
+- docs/plans/waves/reviews/wave-10-word-certification.md
+- services/react-word-editor/app/certification/[runId]/page.tsx
+- services/react-word-editor/lib/certification-bundle.ts
+
+### Proof artifacts
+
+- path: .tmp/wave-10-certification/word-desktop-certification.md | kind: proof-note | required-for: qa-proved
+- path: .tmp/wave-10-certification/word-web-certification.md | kind: proof-note | required-for: qa-proved
+- path: .tmp/wave-10-certification/representative-export-validator.json | kind: validation-report | required-for: qa-proved
+
+### Prompt
+
+```text
+Primary goal:
+- Capture the final human-reviewed certification bundle for the declared v1 fixture and scenario surface.
+
+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/operations/wave-9-manual-certification.md.
+
+Operator command sequence:
+- curl -fsS -X POST "$HARNESS_PUBLIC_URL/api/fixtures/F01-basic-contract/run" > .tmp/wave-10-certification/f01-run.json
+- curl -fsS -X POST "$HARNESS_PUBLIC_URL/api/fixtures/F10-threaded-comments-resolve/run" > .tmp/wave-10-certification/f10-run.json
+- curl -fsS -X POST "$HARNESS_PUBLIC_URL/api/fixtures/F11-redlines-basic/run" > .tmp/wave-10-certification/f11-run.json
+- curl -fsS -X POST "$HARNESS_PUBLIC_URL/api/fixtures/F15-sections-headers-footers/run" > .tmp/wave-10-certification/f15-run.json
+- curl -fsS -X POST "$HARNESS_PUBLIC_URL/api/fixtures/F20-unknown-ooxml-and-alternatecontent/run" > .tmp/wave-10-certification/f20-run.json
+- curl -fsS -X POST "$HARNESS_PUBLIC_URL/api/scenarios/S01/run" > .tmp/wave-10-certification/s01-run.json
+- curl -fsS -X POST "$HARNESS_PUBLIC_URL/api/scenarios/S02/run" > .tmp/wave-10-certification/s02-run.json
+- curl -fsS "$HARNESS_PUBLIC_URL/api/runs/$(jq -r '.validationRun.runId' .tmp/wave-10-certification/s02-run.json)" > .tmp/wave-10-certification/representative-export-validator.json
+
+Specific expectations:
+- attach Word desktop and Word web observations to concrete run ids
+- include both representative scenario artifacts in the final certification bundle
+- keep unsupported or preserve-only caveats explicit in the notes
+- distinguish preserve-only survival passes from supported-roundtrip semantic passes
+
+File ownership (only touch these paths):
+- docs/plans/operations/wave-10-word-certification.md
+- docs/plans/waves/reviews/wave-10-word-certification.md
+- services/react-word-editor/app/certification/[runId]/page.tsx
+- services/react-word-editor/lib/certification-bundle.ts
+- .tmp/wave-10-certification/
+```
+
+## Agent A3: QA Dashboard And Release Diagnostics
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 40
+
+### Context7
+
+- bundle: railway-harness
+- query: "dashboard views, run history APIs, and operator-readable diagnostics for internal QA surfaces"
+
+### Skills
+
+- role-implementation
+- provider-railway
+
+### Components
+
+- railway-test-harness
+- compatibility-and-word-validation
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- services/react-word-editor/app/dashboard/page.tsx
+- services/react-word-editor/app/api/runs/[runId]/route.ts
+- services/react-word-editor/lib/run-history.ts
+- docs/plans/waves/reviews/wave-10-dashboard-proof.md
+
+### Proof artifacts
+
+- path: .tmp/wave-10-certification/dashboard-summary.json | kind: integration-report | required-for: qa-proved
+- path: .tmp/wave-10-certification/run-history-check.json | kind: manifest | required-for: qa-proved
+
+### Prompt
+
+```text
+Primary goal:
+- Give operators one place to inspect regression, certification, validator, accessibility, and performance status before calling the repo qa-proved.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read DESIGN.md.
+- Read services/react-word-editor/README.md.
+
+Specific expectations:
+- dashboard state must come from stored artifacts, not hand-entered summaries
+- make failures and preserve-only caveats visible at a glance
+- keep certification freshness and signoff state visible alongside validator status
+
+File ownership (only touch these paths):
+- services/react-word-editor/app/dashboard/page.tsx
+- services/react-word-editor/app/api/runs/[runId]/route.ts
+- services/react-word-editor/lib/run-history.ts
+- docs/plans/waves/reviews/wave-10-dashboard-proof.md
+- .tmp/wave-10-certification/
+```
+
+## Agent A4: Service QA Hardening
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 35
+
+### Context7
+
+- bundle: validator-dotnet
+- query: "service readiness, structured errors, Docker packaging, retention docs, and QA-proof support surfaces for internal validation services"
+
+### Skills
+
+- role-implementation
+- role-infra
+- provider-railway
+
+### Components
+
+- railway-test-harness
+- openxml-sdk-validator-service
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- services/openxml-validator/Program.cs
+- services/openxml-validator/README.md
+- services/react-word-editor/README.md
+- docs/plans/waves/reviews/wave-10-service-proof.md
+
+### Proof artifacts
+
+- path: .tmp/wave-10-certification/service-health-matrix.json | kind: live-status | required-for: qa-proved
+- path: .tmp/wave-10-certification/service-proof-summary.md | kind: proof-note | required-for: qa-proved
+
+### Prompt
+
+```text
+Primary goal:
+- Harden the internal services enough that the QA bundle includes reliable service diagnostics and docs.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read services/react-word-editor/README.md and services/openxml-validator/README.md.
+- Read docs/reference/live-proof-waves.md.
+
+Specific expectations:
+- keep the validator service validation-only
+- keep the harness internal-only and explicit about storage and retention
+- call out any service assumptions that would block later fleet-ready work
+
+File ownership (only touch these paths):
+- services/openxml-validator/Program.cs
+- services/openxml-validator/README.md
+- services/react-word-editor/README.md
+- docs/plans/waves/reviews/wave-10-service-proof.md
+- .tmp/wave-10-certification/
+```
+
+## Agent A5: Accessibility And DESIGN Conformance Signoff
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: word-editor-ui
+- query: "keyboard navigation, contrast, reduced motion, non-color review cues, and DESIGN.md conformance for final QA"
+
+### Components
+
+- react-editor-ui
+- railway-test-harness
+
+### Exit contract
+
+- completion: integrated
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- docs/plans/waves/reviews/wave-10-accessibility-and-design.md
+
+### Proof artifacts
+
+- path: .tmp/wave-10-certification/accessibility-signoff.md | kind: proof-note | required-for: qa-proved
+- path: .tmp/wave-10-certification/design-conformance.md | kind: proof-note | required-for: qa-proved
+
+### Prompt
+
+```text
+Primary goal:
+- Produce the final accessibility and DESIGN.md conformance signoff for the declared v1 surface.
+
+Required context before coding:
+- Read DESIGN.md.
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/legal-feedback-architecture.md.
+- Read docs/reference/prototype-agent-prompt-legal-fidelity.md.
+- Read docs/reference/word-review-editor-ux-guide.md.
+- Read docs/plans/waves/wave-10.md.
+- Read the current editor and harness QA surfaces, plus the current `/demo`
+  prototype route and fixtures.
+
+Specific expectations:
+- verify keyboard navigation, focus-visible states, contrast, reduced motion, and non-color review cues
+- verify that the document surface remains central and the review chrome remains secondary
+- treat any contradiction with DESIGN.md or accessibility requirements as a blocking issue, not a nice-to-have
+- review the prototype as the intended future-shell reference and call out any
+  meaningful drift in table communication, preserve-only trust cues, or curated
+  browser-typography posture
+- do not translate prototype aspirations into unsupported Wave 10 product claims
+- call out any QA-signed-off wording or layout that would make later first-class
+  tables or font-substitution messaging harder to land cleanly
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-10-accessibility-and-design.md
+- .tmp/wave-10-certification/
+```
+
+## Agent A6: Performance Budget And Large-Document Signoff
+
+### Executor
+
+- profile: proof-owner
+- retry-policy: sticky
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "large-document performance budgets, export latency, review interaction latency, and final QA performance evidence"
+
+### Components
+
+- react-editor-ui
+- command-and-transaction-runtime
+- compatibility-and-word-validation
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- docs/plans/waves/reviews/wave-10-performance-signoff.md
+
+### Proof artifacts
+
+- path: .tmp/wave-10-certification/performance-budget.json | kind: integration-report | required-for: qa-proved
+- path: .tmp/wave-10-certification/large-doc-smoke.json | kind: integration-report | required-for: qa-proved
+
+### Prompt
+
+```text
+Primary goal:
+- Produce the final bounded performance signoff for the declared v1 surface.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/waves/wave-10.md.
+- Read the Wave 9 performance smoke output and the current staging routes.
+
+Specific expectations:
+- define explicit budgets for load, review navigation, accept or reject latency, and export on representative large documents
+- record degradations honestly rather than hiding them inside aggregate numbers
+- block closure if large-document smoke regresses past the declared QA tolerance
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-10-performance-signoff.md
+- .tmp/wave-10-certification/
+```
+
+## Agent A7: Release Certification Auditor
+
+### Role prompts
+
+- docs/agents/wave-cont-qa-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "artifact consistency, support-boundary honesty, certification freshness, and final release-style audit before qa-proved"
+
+### Components
+
+- compatibility-and-word-validation
+- react-editor-ui
+- railway-test-harness
+
+### Exit contract
+
+- completion: integrated
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- docs/plans/waves/reviews/wave-10-release-audit.md
+
+### Proof artifacts
+
+- path: .tmp/wave-10-certification/release-audit-check.json | kind: integration-report | required-for: qa-proved
+
+### Prompt
+
+```text
+Primary goal:
+- Audit the final Wave 10 bundle the way a skeptical release reviewer would, without granting release-ready status yet.
+
+Required context before coding:
+- Read docs/reference/ooxml-compliance.md.
+- Read docs/reference/repository-guidance.md.
+- Read docs/plans/current-state.md.
+- Read docs/plans/waves/wave-10.md and all Wave 10 proof notes.
+
+Specific expectations:
+- block closure if the docs, validator evidence, Word notes, accessibility signoff, and performance signoff disagree
+- block closure if any supported-roundtrip or preserve-only claim lacks a matching artifact trail
+- block closure if the final docs quietly imply fleet-ready or public-demo readiness before Wave 11
+- block closure if the QA bundle or docs accidentally collapse the deferred
+  legal-fidelity packet into the active v1 contract
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-10-release-audit.md
+- .tmp/wave-10-certification/
+```