@beyondwork/docx-react-component 1.0.0 → 1.0.2

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

@@ -1,552 +0,0 @@
-# Wave 9 - Internal Pilot-Live Editor Loop And Workflow Validation
-
-**Commit message**: `Build: pilot the end-to-end editor loop on Railway`
-
-## Component promotions
-
-- canonical-document-model: pilot-live
-- command-and-transaction-runtime: pilot-live
-- comments-and-anchor-mapping: pilot-live
-- tracked-changes-and-review-actions: pilot-live
-- docx-import-and-normalization: pilot-live
-- docx-export-and-serialization: pilot-live
-- unsupported-ooxml-preservation: pilot-live
-- compatibility-and-word-validation: pilot-live
-- react-editor-ui: pilot-live
-- railway-test-harness: pilot-live
-
-## Scope note
-
-Wave 9 is the first live wave that may claim the full end-to-end editor loop on Railway staging. It is not enough to show that the editor loads. This wave must prove that realistic reviewer tasks, exported artifacts, validator output, manual Word observations, and run history all travel through the same staging-backed pipeline.
-
-It must prove:
-
-- representative release-gate fixture runs through the harness-controlled editor path
-- scenario runs for `S01` and `S02` through the same artifact pipeline
-- exported artifacts validated through the internal validator service
-- reviewer-task usability and bounded performance smoke on the same live surface
-
-Wave 9 also needs to keep the live harness and sample-session story aligned with
-the deferred legal-fidelity expansion packet for future first-class tables and
-curated browser-font approximation. Pilot-live proof must stay within the
-declared v1 surface while avoiding UI or artifact assumptions that would later
-conflict with that expansion.
-
-## Entry criteria
-
-- Wave 8 proof artifacts, restart checks, accessibility baseline, and security review are current.
-- Wave 7 has already promoted `tracked-changes-and-review-actions` to `baseline-proved`, so Wave 9 is not the place to discover basic review-boundary regressions.
-- The harness is using the real `WordReviewEditor` package path, not a placeholder or reduced shell.
-
-## Promotion conditions
-
-- live runs for release-gate fixtures and both representative scenarios are stored and reproducible
-- exported artifacts, validator reports, and manual Word notes all attach to the same run ids
-- reviewer-task usability passes on staging without Sev-1 or Sev-2 trust blockers
-- bounded performance smoke is recorded for representative plain-text, comment-heavy, and redline-heavy paths
-- fixture runs and manual uploads use the same materially relevant runtime path unless the docs and artifacts explain the difference
-
-## Prototype review rule
-
-Wave 9 remains a pilot-live proof wave for the declared v1 surface. Any
-design-facing, demo-facing, or reviewer-workflow review in this wave must review
-the current prototype so the staging editor loop is judged against the intended
-future UX rather than only against local implementation convenience.
-
-Required prototype 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/review/prototype-review-workspace.tsx`
-- `services/react-word-editor/lib/demo-fixtures.ts`
-
-This review is an alignment check, not a support expansion. Pilot-live claims
-must still stay inside the active v1 contract.
-
-## Deploy environments
-
-- staging: railway-cli (internal Railway validation environment)
-
-## Context7 defaults
-
-- bundle: railway-harness
-- query: "end-to-end editor embedding, staged Railway validation flows, reviewer workflow capture, and artifact-driven pilot proof"
-
-## Agent A0: cont-QA
-
-### Role prompts
-
-- docs/agents/wave-cont-qa-role.md
-
-### Executor
-
-- profile: deep-review
-
-### Context7
-
-- bundle: word-editor-testing
-- query: "pilot-live proof discipline for end-to-end editor flows, reviewer tasks, and compatibility claims"
-
-### Prompt
-
-```text
-Primary goal:
-- Refuse closure unless the end-to-end editor loop is proven through live artifacts on Railway, not only local tests or screenshots.
-
-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-8.md.
-
-Specific expectations:
-- pilot-live requires live artifact capture for real fixture runs
-- compatibility claims must include exported-doc validation results, not only UI screenshots
-- pilot claims must be backed by stored live artifacts for both release-gate and scenario runs
-- usability or performance blockers on the real review loop are not polish notes; they block pilot-live
-
-File ownership (only touch these paths):
-- docs/plans/waves/reviews/wave-9-cont-qa.md
-```
-
-## Agent A8: Integration Steward
-
-### Role prompts
-
-- docs/agents/wave-integration-role.md
-
-### Executor
-
-- profile: deep-review
-
-### Context7
-
-- bundle: railway-harness
-- query: "integration of the embedded editor, harness storage, live proof, validator linkage, and pilot workflow evidence"
-
-### Prompt
-
-```text
-Primary goal:
-- Decide whether the editor as a whole has actually crossed from baseline-proved into pilot-live.
-
-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-9.md.
-
-Specific expectations:
-- block closure if the harness still uses stubbed editor content
-- block closure if pilot runs skip both representative scenario artifacts `S01` and `S02`
-- block closure if fixture runs and manual uploads use materially different runtime paths without clear evidence
-- block closure if validator output, exported artifacts, and certification notes are not linked to the same run ids
-
-File ownership (only touch these paths):
-- .tmp/main-wave-launcher/integration/wave-9.md
-- .tmp/main-wave-launcher/integration/wave-9.json
-```
-
-## Agent A9: Documentation Steward
-
-### Role prompts
-
-- docs/agents/wave-documentation-role.md
-
-### Executor
-
-- profile: docs-pass
-
-### Context7
-
-- bundle: railway-harness
-- query: "documenting the internal pilot behavior, reviewer tasks, performance expectations, and evidence trust model"
-
-### Prompt
-
-```text
-Primary goal:
-- Update shared-plan docs and operator notes for the internal pilot-live end-to-end loop, including reviewer workflow and performance evidence.
-
-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/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.
-
-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
-- docs/plans/operations/wave-9-manual-certification.md
-```
-
-## Agent A1: Real Editor Embedding In The Harness
-
-### Executor
-
-- profile: implement-fast
-- budget.minutes: 45
-
-### Context7
-
-- bundle: word-editor-ui
-- query: "embedding a complex React editor in a host app, imperative refs, session lifecycle management, and trustworthy staging wiring"
-
-### Skills
-
-- role-implementation
-- domain-editor-architecture
-- provider-railway
-
-### Components
-
-- react-editor-ui
-- railway-test-harness
-
-### Exit contract
-
-- completion: authoritative
-- durability: durable
-- proof: integration
-- doc-impact: owned
-
-### Deliverables
-
-- services/react-word-editor/app/editor/[sessionId]/page.tsx
-- services/react-word-editor/lib/editor-session.ts
-- services/react-word-editor/app/api/sessions/[sessionId]/route.ts
-- docs/plans/waves/reviews/wave-9-editor-embedding.md
-
-### Proof artifacts
-
-- path: .tmp/wave-9-pilot/editor-session-smoke.json | kind: live-run | required-for: pilot-live
-- path: .tmp/wave-9-pilot/editor-load-events.json | kind: integration-report | required-for: pilot-live
-
-### Prompt
-
-```text
-Primary goal:
-- Replace any harness placeholder with the real WordReviewEditor runtime and session wiring.
-
-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:
-- the embedded editor must exercise the same runtime used by the shipped package
-- session load, save, and export must flow through the harness storage layer
-- the staging route must remain honest about any pilot-only controls or internal notes
-- keep the staging shell and session wiring compatible with later typed-table and
-  curated-font expansion rather than hard-coding a UI model that assumes
-  paragraph-only content forever
-
-File ownership (only touch these paths):
-- services/react-word-editor/app/editor/[sessionId]/page.tsx
-- services/react-word-editor/lib/editor-session.ts
-- services/react-word-editor/app/api/sessions/[sessionId]/route.ts
-- docs/plans/waves/reviews/wave-9-editor-embedding.md
-- .tmp/wave-9-pilot/
-```
-
-## Agent A2: Fixture Run Automation And Artifact Capture
-
-### Executor
-
-- profile: implement-fast
-- budget.minutes: 45
-
-### Context7
-
-- bundle: railway-harness
-- query: "route handlers for fixture runs, artifact capture, linked validator results, and validation history in a Next.js internal tool"
-
-### 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/api/fixtures/[fixtureId]/run/route.ts
-- services/react-word-editor/app/api/scenarios/[scenarioId]/run/route.ts
-- services/react-word-editor/app/api/validate/route.ts
-- services/react-word-editor/lib/run-artifacts.ts
-- docs/plans/waves/reviews/wave-9-fixture-runner.md
-
-### Proof artifacts
-
-- path: .tmp/wave-9-pilot/fixture-runner-smoke.json | kind: live-run | required-for: pilot-live
-- path: .tmp/wave-9-pilot/artifact-manifest.json | kind: manifest | required-for: pilot-live
-- path: .tmp/wave-9-pilot/run-linkage-check.json | kind: integration-report | required-for: pilot-live
-
-### Prompt
-
-```text
-Primary goal:
-- Make the harness capable of running selected fixtures end to end and storing the resulting export, validator, and manual-certification artifacts under one linked run story.
-
-Required context before coding:
-- Read docs/reference/repository-guidance.md.
-- Read docs/research/agent-context-sources.md.
-- Read services/react-word-editor/README.md.
-- Read docs/reference/ooxml-compliance.md.
-
-Specific expectations:
-- keep fixture runs machine-visible and reproducible
-- validator calls must use the internal Railway hostname server-side only
-- support scenario runs for `S01` and `S02` without collapsing them into the frozen fixture registry
-- keep run ids stable across exported artifact, validator, and manual-note attachment
-
-File ownership (only touch these paths):
-- services/react-word-editor/app/api/fixtures/[fixtureId]/run/route.ts
-- services/react-word-editor/app/api/scenarios/[scenarioId]/run/route.ts
-- services/react-word-editor/app/api/validate/route.ts
-- services/react-word-editor/lib/run-artifacts.ts
-- docs/plans/waves/reviews/wave-9-fixture-runner.md
-- .tmp/wave-9-pilot/
-```
-
-## Agent A3: Pilot-Live Proof Owner
-
-### Executor
-
-- profile: proof-owner
-- retry-policy: sticky
-
-### Context7
-
-- bundle: railway-harness
-- query: "capturing live fixture-run evidence, linked export artifacts, validator results, and manual notes from an internal Railway harness"
-
-### 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/waves/reviews/wave-9-live-proof.md
-
-### Proof artifacts
-
-- path: .tmp/wave-9-pilot/harness-status.json | kind: live-status | required-for: pilot-live
-- path: .tmp/wave-9-pilot/f01-run.json | kind: live-run | required-for: pilot-live
-- path: .tmp/wave-9-pilot/f11-run.json | kind: live-run | required-for: pilot-live
-- path: .tmp/wave-9-pilot/s01-run.json | kind: live-run | required-for: pilot-live
-- path: .tmp/wave-9-pilot/s02-run.json | kind: live-run | required-for: pilot-live
-- path: .tmp/wave-9-pilot/latest-export-validator.json | kind: validation-report | required-for: pilot-live
-- path: .tmp/wave-9-pilot/manual-certification-notes.md | kind: proof-note | required-for: pilot-live
-- path: .tmp/wave-9-pilot/run-linkage-check.json | kind: integration-report | required-for: pilot-live
-
-### Prompt
-
-```text
-Primary goal:
-- Capture the pilot-live proof bundle for the end-to-end editor loop on selected fixtures with linked validator and manual-review evidence.
-
-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-8-railway-staging.md.
-
-Operator command sequence:
-- railway service status -s react-word-editor -e staging --json > .tmp/wave-9-pilot/harness-status.json
-- curl -fsS -X POST "$HARNESS_PUBLIC_URL/api/fixtures/F01-basic-contract/run" > .tmp/wave-9-pilot/f01-run.json
-- curl -fsS -X POST "$HARNESS_PUBLIC_URL/api/fixtures/F11-redlines-basic/run" > .tmp/wave-9-pilot/f11-run.json
-- curl -fsS -X POST "$HARNESS_PUBLIC_URL/api/scenarios/S01/run" > .tmp/wave-9-pilot/s01-run.json
-- curl -fsS -X POST "$HARNESS_PUBLIC_URL/api/scenarios/S02/run" > .tmp/wave-9-pilot/s02-run.json
-- curl -fsS "$HARNESS_PUBLIC_URL/api/runs/$(jq -r '.validationRun.runId' .tmp/wave-9-pilot/s02-run.json)" > .tmp/wave-9-pilot/latest-export-validator.json
-
-Specific expectations:
-- include one plain-text fixture and one redline fixture at minimum
-- include both representative scenario artifacts in the pilot bundle
-- record any manual Word reopen observations in manual-certification-notes.md rather than implying them
-- confirm that validator output and manual notes both reference the same run ids as the exported artifacts
-
-File ownership (only touch these paths):
-- docs/plans/waves/reviews/wave-9-live-proof.md
-- .tmp/wave-9-pilot/
-```
-
-## Agent A4: Manual Certification Capture Surface
-
-### Executor
-
-- profile: implement-fast
-- budget.minutes: 40
-
-### Context7
-
-- bundle: word-editor-ui
-- query: "operator-facing certification capture surfaces and concise history views in a Next.js internal tool"
-
-### Skills
-
-- role-implementation
-- provider-railway
-
-### Components
-
-- compatibility-and-word-validation
-- railway-test-harness
-
-### Exit contract
-
-- completion: integrated
-- durability: durable
-- proof: integration
-- doc-impact: owned
-
-### Deliverables
-
-- services/react-word-editor/app/certification/page.tsx
-- services/react-word-editor/app/api/certification/route.ts
-- services/react-word-editor/lib/certification-store.ts
-- docs/plans/operations/wave-9-manual-certification.md
-
-### Proof artifacts
-
-- path: .tmp/wave-9-pilot/certification-ui-smoke.json | kind: integration-report | required-for: pilot-live
-- path: .tmp/wave-9-pilot/certification-store-check.json | kind: manifest | required-for: pilot-live
-
-### Prompt
-
-```text
-Primary goal:
-- Give the pilot operators a structured place to record Word desktop and Word web observations against live runs.
-
-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:
-- certification records must attach to concrete harness runs or exported artifacts
-- keep the capture flow concise and evidence-first
-- distinguish "not yet reviewed" from "reviewed and passed"
-
-File ownership (only touch these paths):
-- services/react-word-editor/app/certification/page.tsx
-- services/react-word-editor/app/api/certification/route.ts
-- services/react-word-editor/lib/certification-store.ts
-- docs/plans/operations/wave-9-manual-certification.md
-- .tmp/wave-9-pilot/
-```
-
-## Agent A5: Reviewer Workflow Usability And Performance Pilot
-
-### Executor
-
-- profile: proof-owner
-- retry-policy: sticky
-
-### Context7
-
-- bundle: word-editor-ui
-- query: "realistic legal-review tasks, reviewer trust, and bounded performance budgets on a staging editor surface"
-
-### Components
-
-- react-editor-ui
-- tracked-changes-and-review-actions
-- railway-test-harness
-
-### Exit contract
-
-- completion: authoritative
-- durability: durable
-- proof: live
-- doc-impact: owned
-
-### Deliverables
-
-- docs/plans/waves/reviews/wave-9-usability-and-performance.md
-
-### Proof artifacts
-
-- path: .tmp/wave-9-pilot/reviewer-task-matrix.md | kind: proof-note | required-for: pilot-live
-- path: .tmp/wave-9-pilot/performance-smoke.json | kind: integration-report | required-for: pilot-live
-
-### Prompt
-
-```text
-Primary goal:
-- Run the bounded Wave 9 reviewer-task usability and performance pilot on the live staging editor loop.
-
-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-9.md.
-- Read docs/plans/operations/wave-9-manual-certification.md.
-- Read the current `/demo` prototype route and fixture catalog.
-
-Specific expectations:
-- run realistic tasks: open a document, interpret warnings, switch markup modes, navigate comments and revisions, accept or reject a change, export, and inspect stored artifacts
-- record task-level blockers, not just overall impressions
-- measure load, review navigation, accept or reject latency, and export latency on representative plain-text, comment-heavy, and redline-heavy runs
-- treat Sev-1 or Sev-2 trust or performance blockers as pilot blockers
-- compare the live staging review loop against the prototype's intended trust,
-  table, and curated-typography posture, and record meaningful deltas instead of
-  assuming the current staging shell is automatically the right UX
-- do not convert prototype-only table behavior or browser-font approximation into
-  unsupported pilot claims
-- explicitly note whether current reviewer tasks become harder or misleading on
-  table-heavy or font-sensitive documents so the deferred expansion packet has
-  live usability evidence to inherit later
-
-File ownership (only touch these paths):
-- docs/plans/waves/reviews/wave-9-usability-and-performance.md
-- .tmp/wave-9-pilot/
-```

package/docs/plans/waves/deferred/README.md

@@ -1,14 +0,0 @@
-# Deferred Wave Notes
-
-This directory holds wave drafts and contract packets that are not part of the active numbered sequence.
-
-Current deferred item:
-
-- [wave-encrypted-intake.md](/home/coder/docx-react-component/docs/plans/waves/deferred/wave-encrypted-intake.md)
-- [encrypted-intake-contracts.md](/home/coder/docx-react-component/docs/plans/waves/deferred/encrypted-intake-contracts.md)
-
-Historical precursor:
-
-- [legal-feedback-wave-expansion.md](/home/coder/docx-react-component/docs/plans/waves/deferred/legal-feedback-wave-expansion.md) -> promoted into [wave-12.md](/home/coder/docx-react-component/docs/plans/waves/wave-12.md)
-
-Password-to-open Office handling is deferred here because it is currently solved upstream of `WordReviewEditor`. If ownership moves back into the component, restart from these notes instead of silently widening the active Wave 8 through Wave 10 scope.