@beyondwork/docx-react-component 1.0.0

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

@@ -0,0 +1,596 @@
+# Wave 8 - Harness Baseline, Validator Pilot, And Accessibility Hardening
+
+**Commit message**: `Build: baseline Railway harness, pilot validator service, and harden operator trust`
+
+## Component promotions
+
+- railway-test-harness: baseline-proved
+- openxml-sdk-validator-service: pilot-live
+
+## Scope note
+
+Wave 8 establishes the staging harness baseline and the first live validator
+proof. It keeps the harness operator-facing and non-production, focused on
+deployability, artifact storage, validator connectivity, durability, and
+operator trust. Wave 8 also
+owns the first explicit operator proof that a real `.docx` can be loaded into
+the harness, receive a new comment plus a bounded review or redline action,
+export as a new package, and validate that exact export through the
+harness-to-validator path. This is also the first wave where accessibility,
+design-token discipline, and reduced-motion behavior become explicit closure
+gates for the embedded editor shell rather than post-hoc polish.
+
+Promotion note: both Wave 8 promotions still reference the private-mode proof recapture
+called out in the status section below.
+
+Status: hardening landed in source, but Wave 8 closure is blocked pending a fresh private-mode Railway redeploy and proof recapture.
+
+Closure evidence:
+
+- historical public `early-access` harness baseline on `Fabric / early-access`
+- historical mounted `.docx -> add comment -> review action -> export -> validate` proof under `.tmp/wave-8-railway-pilot/`
+- historical validator restart and health evidence retained for comparison only
+- current accessibility/design and security review notes under `docs/plans/waves/reviews/`
+
+Wave 8 still does not widen the active v1 support boundary. It must, however,
+avoid baking in harness or shell decisions that would fight the deferred legal
+fidelity packet for:
+
+- first-class canonical tables
+- table-aware review and trust cues
+- curated browser-font approximation with explicit substitution diagnostics
+
+## Entry criteria
+
+- Wave 7 proof artifacts, trust note, and integration summary are current.
+- Shared docs still distinguish `baseline-proved`, `pilot-live`, and `qa-proved` honestly.
+- The harness remains an internal operator tool, not a customer-facing product.
+
+## Promotion conditions
+
+- the harness persists uploads, exports, certification records, and run artifacts durably enough for repeatable operator review
+- the validator pilot has current live proof, including restart and redeploy evidence
+- a current proof artifact shows the harness can load a real `.docx`, add at least one new comment, perform at least one bounded review or redline action, export the edited package, and validate that exact export through the declared validator path
+- no browser or client path can reach the private validator hostname directly
+- upload validation, storage retention assumptions, and internal-only exposure posture are documented and reviewed
+- the embedded editor shell used in the harness passes the bounded Wave 8 accessibility, token, and reduced-motion baseline
+
+## Prototype review rule
+
+Wave 8 remains a v1 proof-first wave and does not widen the active support
+boundary. Even so, any design-facing, accessibility-facing, or operator-UX
+review in this wave must review the current internal prototype so the baseline
+embedded shell does not drift away from the intended product direction.
+
+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/app/demo/prototype-client.tsx`
+- `services/react-word-editor/lib/demo-fixtures.ts`
+
+This review is for UX alignment only. It must not be used to widen support
+claims for tables, browser-font fidelity, or other deferred architecture slices.
+
+## Deploy environments
+
+- staging: railway-cli (internal Railway validation environment)
+
+## Context7 defaults
+
+- bundle: railway-harness
+- query: "Next.js internal harness routes, Railway deploys, private networking, durable storage, and accessibility-aware operator surfaces"
+
+## Agent A0: cont-QA
+
+### Role prompts
+
+- docs/agents/wave-cont-qa-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: railway-harness
+- query: "baseline harness claims, pilot-live proof discipline, accessibility closure, and Railway artifact trust boundaries"
+
+### Prompt
+
+```text
+Primary goal:
+- Refuse closure unless the harness is baseline-proved, the validator service has real pilot-live proof artifacts, and the bounded Wave 8 accessibility and trust checks are 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-7.md.
+
+Specific expectations:
+- missing live proof artifacts are blocking
+- missing explicit `.docx -> comment -> review/redline -> export -> validate` proof is blocking
+- client-side access to the private validator hostname is blocking
+- the harness must still be clearly internal-only
+- accessibility, reduced-motion, and token-drift review are blocking if the embedded editor shell is materially inconsistent with DESIGN.md
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-8-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 across Next harness routes, validator networking, Railway staging, restart proof, and live-proof bundles"
+
+### Prompt
+
+```text
+Primary goal:
+- Reconcile deploy, runtime, durability, and proof state across the harness and the validator pilot.
+
+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-8.md.
+
+Specific expectations:
+- treat missing deploy or runbook steps as blocking
+- treat stale deploy or restart evidence as blocking
+- block closure if the explicit review-save-validate proof does not identify the exact source fixture, exported package, and validation artifact for the same run
+- block closure if uploads or fixture runs bypass the documented harness-to-validator path
+- block closure if artifact retention, storage durability, or restart assumptions are not grounded in current proof
+
+File ownership (only touch these paths):
+- .tmp/main-wave-launcher/integration/wave-8.md
+- .tmp/main-wave-launcher/integration/wave-8.json
+```
+
+## Agent A9: Documentation Steward
+
+### Role prompts
+
+- docs/agents/wave-documentation-role.md
+
+### Executor
+
+- profile: docs-pass
+
+### Context7
+
+- bundle: railway-harness
+- query: "documenting Railway staging behavior, internal-only posture, accessibility baseline, and proof-first deploy closure"
+
+### Prompt
+
+```text
+Primary goal:
+- Keep the shared-plan docs and the Railway runbook aligned with the harness baseline, validator pilot, durability rules, and accessibility-bound trust posture.
+
+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-8-railway-staging.md
+```
+
+## Agent A1: Harness Persistence And Upload Flows
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 45
+
+### Context7
+
+- bundle: railway-harness
+- query: "Next.js route handlers, file-backed storage, upload validation, and artifact persistence in an internal tool"
+
+### Skills
+
+- role-implementation
+- role-infra
+- provider-railway
+
+### Components
+
+- railway-test-harness
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- services/react-word-editor/app/api/health/route.ts
+- services/react-word-editor/app/api/uploads/route.ts
+- services/react-word-editor/app/api/exports/route.ts
+- services/react-word-editor/app/api/validate/route.ts
+- services/react-word-editor/lib/storage.ts
+- services/react-word-editor/README.md
+
+### Prompt
+
+```text
+Primary goal:
+- Baseline the harness data plane for uploads, exports, stored artifacts, and retention-safe operator review.
+
+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/plans/master-plan.md.
+
+Specific expectations:
+- use volume-backed local storage, not transient memory
+- keep the harness internal and operator-oriented
+- add explicit size, type, and retention assumptions instead of relying on defaults
+- own the harness-side `/api/health` and `/api/validate` routes because the Wave 8
+  live-proof and operator flow depend on them even though they bridge into A3's
+  validator client
+
+File ownership (only touch these paths):
+- services/react-word-editor/app/api/health/route.ts
+- services/react-word-editor/app/api/uploads/route.ts
+- services/react-word-editor/app/api/exports/route.ts
+- services/react-word-editor/app/api/validate/route.ts
+- services/react-word-editor/lib/storage.ts
+- services/react-word-editor/README.md
+```
+
+## Agent A2: Harness Review Dashboard And Session Pages
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 45
+
+### Context7
+
+- bundle: railway-harness
+- query: "Next.js app router dashboards, run history views, session pages, compatibility report browsing, and calm internal UX"
+
+### Skills
+
+- role-implementation
+- provider-railway
+
+### Components
+
+- railway-test-harness
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- services/react-word-editor/app/fixtures/page.tsx
+- services/react-word-editor/app/runs/[runId]/page.tsx
+- services/react-word-editor/app/editor/[sessionId]/page.tsx
+- services/react-word-editor/components/harness-editor-session-client.tsx
+- services/react-word-editor/lib/harness-client.ts
+
+### Prompt
+
+```text
+Primary goal:
+- Baseline the internal harness UX for fixture browsing, session launch, and validation-history inspection without losing the calm, document-first posture.
+
+Required context before coding:
+- Read DESIGN.md.
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read services/react-word-editor/README.md.
+
+Specific expectations:
+- keep the dashboard utilitarian and document-first
+- surface compatibility and validator results without hiding uncertainty
+- make `S01` and `S02` browseable alongside F01-F21 with clear non-release-gate labels
+- avoid raw token drift or accessibility regressions in newly added harness chrome
+- keep the harness shell and run-history surfaces compatible with the deferred
+  legal-fidelity direction for future typed tables, trust messaging, and curated
+  browser typography without implying those slices are already shipped
+
+File ownership (only touch these paths):
+- services/react-word-editor/app/fixtures/page.tsx
+- services/react-word-editor/app/runs/[runId]/page.tsx
+- services/react-word-editor/app/editor/[sessionId]/page.tsx
+- services/react-word-editor/components/harness-editor-session-client.tsx
+- services/react-word-editor/lib/harness-client.ts
+```
+
+## Agent A3: Railway Deploy, Validator Networking, And Retention Runbook
+
+### Executor
+
+- profile: ops-triage
+- budget.minutes: 40
+
+### Context7
+
+- bundle: railway-harness
+- query: "Railway deploys, staging services, private networking, restart expectations, and storage or retention runbooks"
+
+### Skills
+
+- role-infra
+- role-deploy
+- provider-railway
+
+### Components
+
+- railway-test-harness
+- openxml-sdk-validator-service
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- services/react-word-editor/Dockerfile
+- services/openxml-validator/Dockerfile
+- services/react-word-editor/lib/validator-client.ts
+- docs/plans/operations/wave-8-railway-staging.md
+
+### Proof artifacts
+
+- path: .tmp/wave-8-railway-pilot/deploy-runbook-check.json | kind: manifest | required-for: pilot-live
+
+### Prompt
+
+```text
+Primary goal:
+- Wire the harness and validator to deploy cleanly to the same Railway environment with private networking, restart-safe expectations, and documented storage assumptions.
+
+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:
+- use `http://openxml-validator.railway.internal:8080` for service-to-service traffic
+- keep private networking runtime-only and out of build steps
+- document required Railway variables, restart expectations, and retention assumptions explicitly
+
+File ownership (only touch these paths):
+- services/react-word-editor/Dockerfile
+- services/openxml-validator/Dockerfile
+- services/react-word-editor/lib/validator-client.ts
+- docs/plans/operations/wave-8-railway-staging.md
+- .tmp/wave-8-railway-pilot/
+```
+
+## Agent A4: Embedded Editor Accessibility, Motion, And Token Baseline
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: word-editor-ui
+- query: "keyboard flow, focus-visible states, contrast, non-color review cues, reduced motion, and token drift in an embedded editor shell"
+
+### Components
+
+- railway-test-harness
+
+### Exit contract
+
+- completion: integrated
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- docs/plans/waves/reviews/wave-8-accessibility-and-design.md
+
+### Proof artifacts
+
+- path: .tmp/wave-8-railway-pilot/keyboard-walkthrough.md | kind: proof-note | required-for: baseline-proved
+- path: .tmp/wave-8-railway-pilot/reduced-motion-smoke.json | kind: integration-report | required-for: baseline-proved
+- path: .tmp/wave-8-railway-pilot/token-drift-audit.md | kind: proof-note | required-for: baseline-proved
+
+### Prompt
+
+```text
+Primary goal:
+- Establish the bounded Wave 8 accessibility, motion, and token baseline for the editor as embedded in the harness.
+
+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-8.md.
+- Read the relevant editor and harness UI files, including the current `/demo`
+  prototype route and fixtures.
+
+Specific expectations:
+- verify keyboard flow across toolbar, document surface, sidebar, and harness controls
+- verify focus-visible, contrast, non-color revision cues, and reduced-motion behavior
+- record raw token or layout drift as blocking unless explicitly justified
+- review the current prototype as the future-shell reference and call out any
+  material drift between the embedded runtime path and the prototype's intended
+  trust, table, or curated-typography posture
+- do not treat prototype-only table or font ideas as active support claims in
+  Wave 8 closure
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-8-accessibility-and-design.md
+- .tmp/wave-8-railway-pilot/
+```
+
+## Agent A6: Validator Pilot Live Proof
+
+### Executor
+
+- profile: proof-owner
+- retry-policy: sticky
+
+### Context7
+
+- bundle: railway-harness
+- query: "live-proof capture for Railway staging, deploy freshness, restart checks, service status, and validator smoke tests"
+
+### Skills
+
+- role-infra
+- role-deploy
+- provider-railway
+
+### Components
+
+- openxml-sdk-validator-service
+- railway-test-harness
+
+### Exit contract
+
+- completion: live
+- durability: durable
+- proof: live
+- doc-impact: owned
+
+### Deliverables
+
+- docs/plans/waves/reviews/wave-8-live-proof.md
+
+### Proof artifacts
+
+- path: .tmp/wave-8-railway-pilot/validator-status-before-restart.json | kind: live-status | required-for: pilot-live
+- path: .tmp/wave-8-railway-pilot/validator-status-after-restart.json | kind: restart-check | required-for: pilot-live
+- path: .tmp/wave-8-railway-pilot/harness-status.json | kind: live-status | required-for: pilot-live
+- path: .tmp/wave-8-railway-pilot/harness-health.json | kind: live-status | required-for: pilot-live
+- path: .tmp/wave-8-railway-pilot/validation-smoke.json | kind: validation-report | required-for: pilot-live
+- path: .tmp/wave-8-railway-pilot/review-save-validate-proof.md | kind: proof-note | required-for: baseline-proved
+- path: .tmp/wave-8-railway-pilot/review-save-validate-export.docx | kind: export-artifact | required-for: baseline-proved
+- path: .tmp/wave-8-railway-pilot/review-save-validate-validation.json | kind: validation-report | required-for: baseline-proved
+- path: .tmp/wave-8-railway-pilot/deploy-manifest.json | kind: manifest | required-for: pilot-live
+- path: .tmp/wave-8-railway-pilot/artifact-retention-check.json | kind: manifest | required-for: baseline-proved
+
+### Prompt
+
+```text
+Primary goal:
+- Capture the live proof bundle for the Railway validator pilot and harness baseline with explicit freshness, restart, and retention 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:
+- cd services/openxml-validator && railway up -s openxml-validator -e staging
+- cd services/react-word-editor && railway up -s react-word-editor -e staging
+- railway service status -s openxml-validator -e staging --json > .tmp/wave-8-railway-pilot/validator-status-before-restart.json
+- railway redeploy -s openxml-validator -e staging
+- railway service status -s openxml-validator -e staging --json > .tmp/wave-8-railway-pilot/validator-status-after-restart.json
+- railway service status -s react-word-editor -e staging --json > .tmp/wave-8-railway-pilot/harness-status.json
+- curl -fsS "$HARNESS_PUBLIC_URL/api/health" > .tmp/wave-8-railway-pilot/harness-health.json
+- curl -fsS -F "file=@test/fixtures/docx/F01-basic-contract.docx" "$HARNESS_PUBLIC_URL/api/validate" > .tmp/wave-8-railway-pilot/validation-smoke.json
+
+Specific expectations:
+- closure only counts when the declared proof artifacts exist locally and reflect the current deploy
+- capture one explicit live harness proof using a real `.docx`: load the source package, add a new comment, perform a bounded review or redline-capable edit, export the edited package, and validate that exact exported package through the declared validator path
+- the proof note must identify the source fixture, session identifier or run identifier, the concrete review steps taken, the saved export artifact, and the matching validation JSON for that same export
+- if service names differ from the defaults, update the runbook and proof manifest explicitly
+- record storage-retention and artifact-manifest assumptions instead of leaving them implicit
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-8-live-proof.md
+- .tmp/wave-8-railway-pilot/
+```
+
+## Agent A7: Upload And Internal-Network Security Review
+
+### Role prompts
+
+- docs/agents/wave-security-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: railway-harness
+- query: "internal-only service posture, file upload handling, retention boundaries, and private-network trust assumptions for Railway apps"
+
+### Skills
+
+- role-security
+- provider-railway
+
+### Exit contract
+
+- completion: integrated
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- docs/plans/waves/reviews/wave-8-security.md
+
+### Prompt
+
+```text
+Primary goal:
+- Review the upload, storage, retention, and private-network assumptions before the validator pilot is allowed to close.
+
+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 services/react-word-editor/README.md and services/openxml-validator/README.md.
+
+Specific expectations:
+- call out missing size limits, file-type validation, retention gaps, or accidental public exposure
+- call out any browser path that can reach the private validator hostname directly
+- call out any mismatch between documented internal-only posture and the actual staging surface
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-8-security.md
+```