@beyondwork/docx-react-component 1.0.0 → 1.0.2

package/docs/plans/waves/design/wave-1-a1.md

@@ -1,309 +0,0 @@
-# Wave 1 - Architecture Design Packet (A1)
-
-**Agent:** A1 (Architecture Design Packet)
-**Date:** 2026-03-25
-**Status:** ready-for-implementation
-
-## Problem
-
-Wave 1 has to freeze the editor architecture before any implementation wave lands source code. The repo already states the product invariants, but Wave 2 cannot start safely until the following are explicit in one packet:
-
-1. One shared coordinate-space strategy for selections, comment anchors, revisions, and opaque fragments.
-2. One runtime/UI contract that keeps React as a projection and never as source of truth.
-3. One canonical document envelope that is rich enough for OOXML round-trip work instead of collapsing the model to content plus a few ad hoc side stores.
-4. One proof map that assigns exact later-wave evidence for every promoted component and the F01-F21 fixture corpus.
-
-The existing A1 draft already froze the right direction, but it still left three implementation risks:
-
-- the canonical envelope was simplified below the richer schema and runtime research docs
-- the compatibility taxonomy could drift back into unsupported `supported-import-only` or `supported-export-only` states
-- the proof plan mismatched the fixture registry and later wave sequence
-
-## Constraints
-
-- `WordReviewEditor` is the only shipped public component.
-- The shipped editor runs in the main thread with no Web Workers.
-- Canonical structured state is the only source of truth; the DOM is a render target only.
-- All mutations flow through commands, transactions, mappings, and atomic commits.
-- Comments, revisions, and opaque preservation anchors must survive edits through one shared integer position space.
-- Unsupported OOXML is preserved, locked, warned about, or blocks export; it is never silently dropped.
-- `.docx` is treated as an OPC package, so unknown parts and relationships are part of the fidelity contract.
-- The Microsoft Open XML SDK is validation-only and must stay out of the browser bundle.
-- UI must remain calm, contextual, and review-oriented per `DESIGN.md`.
-- Wave 1 owns contract freeze only. It must not silently turn into broad source implementation outside the owned docs.
-
-## Decisions
-
-### D1 - Shared global position space over the canonical main story
-
-Selections, comment anchors, revision anchors, opaque fragment anchors, and other editable-story bindings use one ProseMirror-compatible integer position space over the canonical main story.
-
-- `Position` is an integer.
-- Ranges use `{ from, to }` with `from` inclusive and `to` exclusive.
-- Text node size is the number of Unicode code points.
-- Atomic inline and atomic block leaf nodes each consume size `1`.
-- Container nodes consume `2 + sum(childSizes)`.
-- The document root itself is not counted; position `0` is before its first child.
-- This coordinate space applies only to the editable canonical story plus atomic placeholders inside it.
-- Preserved out-of-band parts such as headers, footers, notes, or unknown package parts are not individually position-addressed unless canonicalized into the main story as atomic placeholders.
-
-### D2 - Anchor remapping is synchronous, atomic, and bias-aware
-
-Every transaction produces a composed mapping. The runtime applies that mapping before subscribers are notified.
-
-- Selection ranges carry boundary association or stickiness so insertions at a boundary map deterministically.
-- Comment and revision anchors carry the same mapping inputs as selections.
-- Preservation fragment bindings carry the same mapping inputs as comment and revision anchors.
-- If a remap invalidates an anchor, the anchor transitions to a detached state with `lastKnownRange` and `reason`; it is not silently deleted.
-- Detached anchors surface a warning through the compatibility or runtime diagnostics layer.
-
-### D3 - CanonicalDocument keeps the richer schema envelope, not a collapsed minimal shell
-
-Wave 1 freezes a richer canonical envelope that matches the research docs and still preserves the repo's three-domain rule.
-
-```ts
-interface CanonicalDocument {
-  schemaVersion: "cds/1.0.0";
-  docId: UUID;
-  createdAt: ISO8601DateTime;
-  updatedAt: ISO8601DateTime;
-  metadata: DocumentMetadata;
-  styles: StylesCatalog;
-  numbering: NumberingCatalog;
-  media: MediaCatalog;
-  content: DocNode;
-  review: ReviewStore;
-  preservation: PreservationStore;
-  diagnostics: DiagnosticStore;
-}
-```
-
-- The three mutation domains that participate in normal editing are `content`, `review`, and `preservation`.
-- `review` owns both comments and revisions.
-- `styles`, `numbering`, `media`, `metadata`, and `diagnostics` are first-class schema surfaces, not implementation leftovers.
-- The envelope is deterministically serializable and versioned from Wave 2 onward.
-
-### D4 - DocumentRuntime is the only mutation authority
-
-`DocumentRuntime` owns the live session. React subscribes to it and dispatches commands into it.
-
-- React never writes canonical state directly.
-- React never keeps its own editable copy of document nodes.
-- React never imports `src/io`, `src/preservation`, or `src/validation` directly.
-- Host-facing imperative methods are thin wrappers over runtime methods.
-- The runtime owns load, dispatch, undo, redo, persistence snapshots, export, warnings, and compatibility reporting.
-
-### D5 - React uses an external-store boundary, not reducer-owned document truth
-
-Wave 1 freezes the runtime/UI boundary around an external store pair plus command dispatch.
-
-- React reads runtime state through `subscribe(...)` plus a pure snapshot getter for rendering.
-- React should use `useSyncExternalStore` or an equivalent external-store subscription pattern.
-- The runtime also exposes a persisted snapshot getter for host persistence and ref APIs.
-- The ref surface remains the public imperative boundary; the DOM is never exposed as the source of truth.
-
-### D6 - All mutations are `command -> transaction -> mapping -> remap -> commit -> notify`
-
-The mutation pipeline is frozen across all implementation waves.
-
-- Commands are the only legal mutation entry.
-- Transactions contain ordered steps plus the composed mapping.
-- The runtime applies content changes first, then remaps review, preservation, and selection state, then commits once.
-- Subscribers and emitted events see only post-remap committed state.
-- There is no lazy remapping pass and no UI-local repair pass after commit.
-
-### D7 - Import and export stay unidirectional and package-first
-
-The IO architecture is frozen as:
-
-`.docx bytes -> OPC reader -> OOXML normalizer -> canonicalizer -> runtime load`
-
-and the inverse:
-
-`canonical state -> serializer -> OPC writer -> .docx bytes`
-
-- React is never part of import or export.
-- The normalizer works on OOXML and OPC concepts, not HTML.
-- The canonicalizer is the boundary where supported content becomes canonical state and unsupported content becomes preservation records or fatal diagnostics.
-- Export only regenerates parts the editor explicitly owns.
-- Preserved parts, relationships, and opaque fragments are reattached during serialization or package writing.
-
-### D8 - The v1 compatibility taxonomy is exactly three classes
-
-Wave 1 freezes the implementation-facing taxonomy to:
-
-- `supported-roundtrip`
-- `preserve-only`
-- `unsupported-fatal`
-
-`supported-import-only` and `supported-export-only` are not part of the v1 editing contract. If a feature cannot safely satisfy `supported-roundtrip`, it must either be `preserve-only` or `unsupported-fatal`.
-
-### D9 - Supported review authoring is intentionally narrower than all imported review markup
-
-Wave 1 freezes the review scope that later implementation agents must build around.
-
-- Supported authoring includes single-paragraph comment ranges and threads.
-- Supported authoring includes tracked insertions and tracked deletions plus accept or reject flows for those types.
-- Imported multi-paragraph editable comment ranges are preserve-only and locked in v1.
-- Imported tracked moves, tracked formatting changes, and tracked structural table or list revisions are preserve-only and locked in v1.
-- Deleting an entire commented range requires an explicit destructive choice instead of silently dropping the comment.
-
-### D10 - Opaque regions are atomic placeholders with preservation-owned payloads
-
-Unsupported inline or block OOXML regions that stay preservable become atomic placeholders in the canonical content tree.
-
-- Canonical placeholder node kinds are `opaque_inline` and `opaque_block`.
-- Both are atomic leaf nodes for coordinate-space purposes.
-- Each placeholder carries `fragmentId` and a UI-linkable warning key.
-- Preservation payloads keep the original XML or package bytes plus the last known anchor range.
-- Commands may delete an opaque node only as a whole-unit action and must surface an explicit destructive warning.
-- Commands may not split, partially edit, or normalize inside an opaque region.
-
-### D11 - Snapshot and compatibility surfaces are separate from render snapshots
-
-Wave 1 freezes a distinction between the runtime's render-facing snapshot and the persisted host-facing snapshot.
-
-- React render subscriptions consume a runtime snapshot or projection, not a persistence artifact.
-- The host-facing persistence artifact remains `PersistedEditorSnapshot`.
-- `PersistedEditorSnapshot` must carry snapshot version, schema version, document identity, save metadata, a serialized `CanonicalDocument`, and compatibility data.
-- Loading a persisted snapshot does not re-run OOXML import.
-- `CompatibilityReport` must include stable feature entries, warnings, errors, and an export-block signal.
-
-### D12 - Proof ownership is part of the contract
-
-Wave 1 freezes later-wave proof ownership so A0 and A8 can reject narrative-only closure.
-
-- Wave 2 repo-lands canonical model, runtime, and React shell seams with unit or smoke proof for envelope shape, position mapping, runtime subscription, and external-store binding.
-- Wave 3 baseline-proves canonical model, runtime, import or export text slice, and React shell behavior on F01-F02.
-- Wave 3 also repo-lands the compatibility-report surface and validator-service contract shape on F01-F02.
-- Wave 4 proves lists, numbering, tables, inline images, and hyperlinks, and baseline-proves the compatibility subsystem with the structural compatibility suite.
-- Wave 5 proves comments and anchor remapping.
-- Wave 6 proves tracked insertions and deletions plus accept or reject.
-- Wave 7 proves preserve-only content survival and malformed-document fail-safe behavior.
-- Wave 8 proves the internal harness and validator service deployment path.
-- Wave 9 proves the end-to-end staging loop on selected fixtures and representative scenarios.
-- Wave 10 proves the declared v1 surface against the full regression and Word certification bundle.
-
-## Assumptions
-
-- Wave 2 and later waves will use ProseMirror `Step`, `StepMap`, and `Mapping` machinery underneath repo-owned wrapper types rather than re-implementing those algorithms from scratch.
-- The editable canonical story is the main document story; headers, footers, notes, and other preserve-only stories remain out-of-band until a later wave explicitly canonicalizes them.
-- A browser-compatible ZIP or OPC library is available for runtime import and export without introducing Node-only primitives into the shipped bundle.
-- One `DocumentRuntime` instance exists per mounted `WordReviewEditor` instance.
-- Threaded comment metadata such as replies and resolution state remains part of the review model even when some OOXML details require preserve-only handling on initial waves.
-
-## Open Questions
-
-- `EditorRangeRef` still needs an exact public projection encoding for host-visible warnings and diagnostics. A2 and A4 must pick the field shape without changing the underlying position model.
-- The exact UI treatment for detached or orphaned imported anchors still belongs to A4, but the underlying data-state transition is frozen by D2 and D9.
-
-## Interface Impacts
-
-| Surface | Owner | Exact impact |
-| --- | --- | --- |
-| `docs/plans/waves/specs/wave-1-runtime-contracts.md` | A2 | Freeze the external-store runtime contract around `subscribe`, a render snapshot getter, command dispatch, undo/redo, `getPersistedSnapshot`, `exportDocx`, warning access, and compatibility reporting. |
-| `docs/reference/public-api.md` | A2 | Keep `WordReviewEditorRef.getSnapshot()` as the host-facing persisted snapshot API, keep the current public imperative categories unchanged, and make any `EditorRangeRef` projection runtime-derived rather than DOM-path-derived. |
-| `src/model/canonical.ts` | A2 | Define `CanonicalDocument` with exact top-level keys `schemaVersion`, `docId`, `createdAt`, `updatedAt`, `metadata`, `styles`, `numbering`, `media`, `content`, `review`, `preservation`, `diagnostics`. |
-| `src/core/position.ts` | A2 | Define `Position`, `DocRange`, mapping wrappers, selection association or stickiness, and remap helpers used by runtime, review, and preservation. |
-| `src/core/transaction.ts` | A2 | Define the transaction envelope and command boundary that preserve the D6 commit order. |
-| `src/review/store.ts` | A4 | Define review anchors with exact keys for `kind`, anchor payload, detached-state payload, and remap behavior; keep comment authoring to single-paragraph ranges for v1. |
-| `src/preservation/store.ts` | A3 | Define opaque fragment records with `fragmentId`, payload bytes or XML, `lastKnownRange`, `featureClass`, and the package-part manifest. |
-| `src/runtime/index.ts` | A2 | Implement the sole mutation authority and guarantee that remapping completes before any subscriber notification. |
-| `src/io/*` | A3 | Keep import and export package-first; no direct UI imports; no HTML intermediary contract. |
-| `src/validation/compatibility-report.ts` | A3 | Freeze `CompatibilityReport` around stable entries plus `warnings`, `errors`, and `blockExport`. |
-| `docs/reference/ooxml-compliance.md` | A3 | Remove `supported-import-only` and `supported-export-only` from the v1 contract, restate the feature classes as `supported-roundtrip`, `preserve-only`, and `unsupported-fatal`, and align release-gate language to the frozen three-class taxonomy. |
-| `src/ui/WordReviewEditor.tsx` | A4 | Bind React to the runtime external store only; no document-truth reducer in React; no direct IO or preservation calls. |
-| `docs/plans/master-plan.md` | A9 | Update the Wave 1 architecture summary so it reflects the richer canonical envelope, the three mutable editing domains, the external-store runtime/UI boundary, and the frozen three-class compatibility taxonomy. |
-| `docs/plans/current-state.md` | A9 | Update the current-state narrative to say Wave 1 contract-freeze docs landed and the promoted components are `contract-frozen`, while implementation proof still belongs to later waves. |
-| `docs/plans/component-cutover-matrix.md` | A9 | Update all Wave 1 promoted components to `contract-frozen` and cite this packet plus `wave-1-component-boundaries.md` as the supporting freeze docs. |
-| `docs/plans/component-cutover-matrix.json` | A9 | Set `currentLevel` to `contract-frozen` for `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`, and `react-editor-ui`. |
-
-## Validation Plan
-
-### Wave 1
-
-- A1 lands this design packet and `wave-1-component-boundaries.md`.
-- A2, A3, and A4 land their owned contract docs against this packet rather than re-deriving architecture.
-- A3 aligns `docs/reference/ooxml-compliance.md` to the frozen three-class taxonomy before downstream compatibility docs claim closure.
-- A9 aligns shared-plan docs and the component matrix to `contract-frozen`.
-
-### Wave 2
-
-- A2 repo-lands canonical model and runtime boundaries with unit tests for schema construction, position arithmetic, mapping composition, and runtime subscription.
-- A4 repo-lands the React shell and external-store binding with load, focus, ready, and imperative-ref smoke checks that do not introduce React-owned document truth.
-
-### Wave 3
-
-- A2 baseline-proves canonical model and runtime behavior on F01 and F02 through text-edit, remap, and undo or redo checks that run through the real transaction pipeline.
-- A3 baseline-proves the text slice with fixture-backed import or export checks on F01 and F02, including whitespace, tabs, hard breaks, paragraph structure, and heading/style references embedded in those fixtures.
-- A3 repo-lands compatibility-report generation and validator-service contract shape on the same F01-F02 slice.
-- A4 baseline-proves the React shell with runtime-driven editing, toolbar, and ref smoke that renders only from runtime snapshots.
-
-### Wave 4
-
-- A3 proves F03-F08 for numbering, lists, tables, merged-cell preservation, inline images, and hyperlinks.
-- A3 baseline-proves compatibility-and-word-validation with structural compatibility checks, feature-class assertions, and export-risk gating for the Wave 3 and Wave 4 fixture set.
-
-### Wave 5
-
-- A4 proves F09-F10 for comment anchoring, imported thread structure, resolution metadata, and anchor remapping through edits.
-- Any imported comment case outside the supported authoring envelope must remain locked and explicitly diagnosed.
-
-### Wave 6
-
-- A4 proves F11-F14 for tracked insertions, deletions, paragraph-join or split cases under revisions, and preserve-only structural revision handling.
-- Accept or reject flows must leave no dangling revision ids or invalid anchors.
-
-### Wave 7
-
-- A3 proves F15-F21 for preserve-only sections, headers or footers, notes, fields, content controls, custom XML, unknown OOXML, unknown package parts, and malformed-document fail-safe behavior.
-- Preservation proof must include byte-stable or semantically stable survival checks plus export-block behavior for malformed docs.
-
-### Wave 8
-
-- The internal Railway harness and Open XML validator service prove their deployment and contract health.
-
-### Wave 9
-
-- Selected end-to-end fixture and scenario flows run on staging using the real editor loop plus stored artifacts.
-
-### Wave 10
-- The full fixture corpus and manual Word certification bundle gate v1 closure.
-
-## Implementation Handoff
-
-### A2 - Runtime And Host Contract Lock
-
-- Freeze the runtime as an external store plus mutation authority. The runtime needs a render snapshot getter and a persisted snapshot getter; do not collapse them into one ambiguous method.
-- Define the canonical model around the D3 envelope instead of the older minimal `content/review/preservation only` shell.
-- Keep public ref categories unchanged from current public API docs.
-- Do not reintroduce a React-owned document reducer, a controlled-keystroke API, or DOM-derived document truth.
-- Repo-land proof expected in Wave 2: unit tests for mapping, runtime subscription, and deterministic envelope serialization.
-- Baseline proof expected in Wave 3: F01-F02 text-edit, remap, and undo or redo checks through the real transaction pipeline.
-
-### A3 - OOXML, Preservation, And Fixture Contract Lock
-
-- Freeze import and export around OPC reader, OOXML normalizer, canonicalizer, serializer, and OPC writer boundaries.
-- Freeze the three-class compatibility taxonomy and remove any implementation drift toward import-only or export-only feature states.
-- Define opaque fragment records and preserved package-part manifests so Wave 7 can implement preservation without reopening architecture.
-- Bind F01-F21 to the wave ownership in this packet. Do not reuse the earlier inconsistent mapping.
-- Proof expected across Waves 3, 4, and 7: F01-F02 baseline text import or export checks plus compatibility-report skeleton in Wave 3, F03-F08 compatibility baseline in Wave 4, and F15-F21 preservation plus export-block checks in Wave 7.
-
-### A4 - Review And UI Contract Lock
-
-- Freeze review anchors around the D1 and D2 position model, including detached-anchor behavior after destructive edits.
-- Keep supported authoring to the D9 envelope: single-paragraph comments plus tracked insertions and deletions.
-- Use the runtime external-store boundary only. UI panels read projections from runtime state and dispatch commands back to the runtime.
-- Do not make imported preserve-only review structures editable in the browser just because they can be rendered.
-- Repo-land proof expected in Wave 2 and baseline proof expected in Wave 3 for the React shell: external-store wiring, runtime-driven rendering, and imperative-ref smoke without React-owned document truth.
-- Review proof expected in Waves 5 and 6: comment-anchor fixtures, review remap tests, and accept or reject unit tests.
-
-### A8 - Integration Steward
-
-- Use this packet and `wave-1-component-boundaries.md` as the architectural baseline for Wave 1 integration review.
-- Reject any downstream contract doc that contradicts the D1 coordinate space, D4 or D5 runtime boundary, D8 taxonomy, or D12 proof ownership.
-
-### A9 - Documentation Steward
-
-- Update shared docs so the component matrix and plan docs reflect Wave 1 as `contract-frozen`, not merely `inventoried`.
-- Point shared-plan readers at this packet and the component-boundaries spec as the implementation handoff docs for Wave 2 and later waves.

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

@@ -1,5 +0,0 @@
-# Wave Reviews
-
-This directory stores review, proof, QA, security, and live-proof notes emitted by wave agents.
-
-Proof-first waves also write machine-visible artifacts under `.tmp/`.

package/docs/plans/waves/reviews/wave-0-cont-qa.md

@@ -1,151 +0,0 @@
-# Wave 0 cont-QA Report
-
-## 2026-03-25T18:29:30Z Closure Review
-
-Wave 0 implementation evidence is materially stronger than the stale shared summary implies, but the wave is still blocked by canonical closure-state gaps rather than by missing scaffold code.
-
-Evidence reviewed:
-
-- `README.md`
-- `docs/reference/repository-guidance.md`
-- `docs/research/agent-context-sources.md`
-- `docs/roadmap.md`
-- `docs/plans/master-plan.md`
-- `docs/plans/current-state.md`
-- `docs/plans/component-cutover-matrix.md`
-- `docs/plans/component-cutover-matrix.json`
-- `docs/plans/waves/wave-0.md`
-- `.tmp/main-wave-launcher/messageboards/wave-0.md`
-- `.tmp/main-wave-launcher/inboxes/wave-0/shared-summary.md`
-- `.tmp/main-wave-launcher/inboxes/wave-0/A0.md`
-- `.tmp/main-wave-launcher/integration/wave-0.md`
-- `.tmp/main-wave-launcher/reducer/wave-0.json`
-- `.tmp/main-wave-launcher/results/wave-0/attempt-1/A1.json`
-- `.tmp/main-wave-launcher/results/wave-0/attempt-2/A9.json`
-- `.tmp/main-wave-launcher/status/wave-0-0-a9.summary.json`
-- `.tmp/main-wave-launcher/traces/wave-0/attempt-1/logs/0-a1.log`
-- `.tmp/main-wave-launcher/coordination/wave-0.jsonl`
-
-Validation rerun by A0:
-
-- `pnpm --filter @docx-react-component/react-word-editor-harness test` passed.
-- `pnpm --filter @docx-react-component/react-word-editor-harness build` passed.
-- `dotnet build services/openxml-validator/OpenXmlValidator.Api.csproj` passed.
-- `pnpm exec wave doctor --json` passed.
-- `pnpm exec wave launch --lane main --dry-run --no-dashboard` passed.
-
-Exit contract and promotion review:
-
-- A1 landed durable scaffold evidence for the promoted surfaces in `src/component-inventory.md`, the service and source READMEs, `services/react-word-editor/lib/harness-config.json`, `services/react-word-editor/lib/harness-config.ts`, and `services/react-word-editor/lib/harness-config.test.mjs`.
-- The component matrix artifacts already match the declared wave-0 promotions. `docs/plans/component-cutover-matrix.md` and `docs/plans/component-cutover-matrix.json` show `inventoried` for the editor-side components and `repo-landed` for `railway-test-harness` and `openxml-sdk-validator-service`.
-- The local validation rerun confirms the scaffold is buildable enough for the declared `inventoried` and `repo-landed` targets.
-
-Blocking set:
-
-1. Canonical A1 proof state is still unresolved. `wave control status --lane main --wave 0 --json` reports blocking edge `coord-blocker-6449b176`, and that blocker cites a mismatch between `.tmp/main-wave-launcher/traces/wave-0/attempt-1/logs/0-a1.log` and `.tmp/main-wave-launcher/results/wave-0/attempt-1/A1.json`. The trace log contains A1 `wave-proof`, `wave-doc-delta`, and `wave-component` markers, but the canonical result artifact is synthesized with `proof.state = not_applicable`, `implementation.docDelta.state = none`, and an empty `components` array. The reducer still records `Agent A1 reported a proof gap.`
-2. Documentation closure is not complete. A9 narrowed the shared-plan delta in `coord-decision-72e1af76`, but the required update to `docs/plans/current-state.md` has not landed. The decision detail names the missing facts: `src/component-inventory.md` and the harness config unit proof in `services/react-word-editor/lib/harness-config.test.mjs`. `docs/plans/current-state.md` still omits both, and no `[wave-doc-closure]` marker is present in `.tmp/main-wave-launcher/coordination/wave-0.jsonl`. `.tmp/main-wave-launcher/status/wave-0-0-a9.summary.json` shows `docClosure = null` and `terminationReason = "max-turns"`.
-3. Integration closure is not complete. `.tmp/main-wave-launcher/integration/wave-0.md` still recommends `needs-more-work`, and no `[wave-integration]` marker is present in `.tmp/main-wave-launcher/coordination/wave-0.jsonl`. A8 has reduced the blocker set to the canonical A1 artifact mismatch, but integration has not reached `ready-for-doc-closure`.
-
-Closure judgment:
-
-- Architecture: pass. The repo framing, source ownership, component inventory, and service scaffolds are coherent with the repository guidance and wave-0 promotions.
-- Durability: blocked. The canonical implementation result artifact does not carry the proof and component state that the trace log shows, so the authoritative proof surface is inconsistent.
-- Live: pass. No remote deployment was requested for wave 0, and the local harness and validator build checks passed.
-- Docs: blocked. Shared-plan reconciliation is still open because `docs/plans/current-state.md` is missing the exact A9 delta and the required doc-closure marker is absent.
-- Integration: blocked. A8 has an explicit blocker record and no final integration marker.
-
-Required next actions before cont-QA can pass:
-
-- Regenerate or rerun A1 so `.tmp/main-wave-launcher/results/wave-0/attempt-*/A1.json` captures the implementation proof, doc delta, and component markers instead of the synthesized empty state.
-- Update `docs/plans/current-state.md` to mention `src/component-inventory.md` and the harness config unit proof in `services/react-word-editor/lib/harness-config.test.mjs`, then emit `[wave-doc-closure] state=closed` or valid `no-change`.
-- Have A8 emit a final `[wave-integration]` marker after the canonical A1 proof state and documentation closure are actually closed.
-
-[wave-gate] architecture=pass integration=blocked durability=blocked live=pass docs=blocked detail=Canonical A1 result proof is missing and doc closure is still open
-Verdict: BLOCKED
-
-## 2026-03-25T18:48:00Z Closure Sweep
-
-Wave 0 is no longer blocked by A1 implementation proof or by missing shared-plan content. The remaining blocker is the missing documentation-closure artifact from A9.
-
-Evidence reviewed in this sweep:
-
-- `docs/plans/current-state.md`
-- `docs/plans/component-cutover-matrix.md`
-- `docs/plans/component-cutover-matrix.json`
-- `src/component-inventory.md`
-- `services/react-word-editor/lib/harness-config.json`
-- `services/react-word-editor/lib/harness-config.test.mjs`
-- `.tmp/main-wave-launcher/status/wave-0-0-a1.summary.json`
-- `.tmp/main-wave-launcher/status/wave-0-0-a1.envelope.json`
-- `.tmp/main-wave-launcher/status/wave-0-0-a9.summary.json`
-- `.tmp/main-wave-launcher/results/wave-0/attempt-1/A1.json`
-- `.tmp/main-wave-launcher/integration/wave-0.md`
-- `.tmp/main-wave-launcher/integration/wave-0.json`
-- `.tmp/main-wave-launcher/coordination/wave-0.jsonl`
-- `pnpm exec wave control status --lane main --wave 0 --json`
-
-Closure findings:
-
-- A1 exit-contract proof is satisfied in canonical typed artifacts. `.tmp/main-wave-launcher/status/wave-0-0-a1.summary.json` records `proof.state = met`, `docDelta.state = owned`, and 11 accepted component markers. `.tmp/main-wave-launcher/status/wave-0-0-a1.envelope.json` matches that state with `proof.state = satisfied`.
-- All declared Wave 0 component promotions are met. `src/component-inventory.md` inventories the editor-side components at `inventoried`, and `docs/plans/component-cutover-matrix.md` plus `docs/plans/component-cutover-matrix.json` show `repo-landed` for `railway-test-harness` and `openxml-sdk-validator-service`.
-- The A9-owned shared-plan delta is now landed in `docs/plans/current-state.md`. The file explicitly names `src/component-inventory.md` and the harness proof pair `services/react-word-editor/lib/harness-config.json` plus `services/react-word-editor/lib/harness-config.test.mjs`. `docs/roadmap.md`, `docs/plans/master-plan.md`, `docs/plans/migration.md`, and the component matrix artifacts remain coherent as valid no-change surfaces for Wave 0.
-- Integration now recommends closure. `coord-integration-summary-14486cc6` includes `[wave-integration] state=ready-for-doc-closure claims=0 conflicts=0 blockers=0 detail=A1 proof is satisfied; A9 doc marker and A0 QA rerun remain`, and no later coordination evidence reopens a material implementation or integration contradiction.
-- No active rerun request exists. `wave control status --lane main --wave 0 --json` reports `rerunRequest = null` and no active proof bundles.
-
-Smallest remaining blocking set:
-
-1. Documentation closure is still not explicit. `.tmp/main-wave-launcher/status/wave-0-0-a9.summary.json` shows `docClosure = null`, `structuredSignalDiagnostics.docClosure.acceptedCount = 0`, and `terminationReason = \"max-turns\"`.
-2. The coordination log still contains no A9-emitted `[wave-doc-closure] state=closed|no-change ...` marker. Without that owner-authored closure signal, the shared-plan docs gate remains open even though `docs/plans/current-state.md` is now correct.
-
-Required final delta before PASS:
-
-- A9 must emit a documentation-closure artifact. The acceptable closure is `state=closed` because `docs/plans/current-state.md` changed; the note must cover at least `docs/plans/current-state.md` and state that `docs/roadmap.md`, `docs/plans/master-plan.md`, `docs/plans/migration.md`, and `docs/plans/component-cutover-matrix.{md,json}` are valid no-change for Wave 0.
-
-Closure judgment:
-
-- Architecture: pass. The repo framing, source-owned inventory, harness config proof surface, and component maturity docs are coherent with Wave 0.
-- Integration: pass. A8's latest integration output is positive and not contradicted by later landed evidence.
-- Durability: pass. Canonical proof artifacts and the previously rerun local validation commands are sufficient for the declared `inventoried` and `repo-landed` targets.
-- Live: pass. No deployment was requested; local harness and validator proof surfaces are present.
-- Docs: blocked. The content is aligned, but the required A9 documentation-closure artifact is still missing.
-
-[wave-gate] architecture=pass integration=pass durability=pass live=pass docs=blocked detail=A9-doc-closure-marker-missing-after-landed-current-state-delta
-Verdict: BLOCKED
-
-## 2026-03-25T19:12:00Z Manual Final Closure
-
-Wave 0 is ready to close. The only remaining failure was procedural: A0 hit the runtime turn ceiling before emitting the final structured gate marker, after A9 and A8 had already closed the substantive blockers.
-
-Evidence reviewed in this final closure:
-
-- `.tmp/main-wave-launcher/status/wave-0-0-a1.summary.json`
-- `.tmp/main-wave-launcher/status/wave-0-0-a1.envelope.json`
-- `.tmp/main-wave-launcher/status/wave-0-0-a8.summary.json`
-- `.tmp/main-wave-launcher/status/wave-0-0-a9.summary.json`
-- `.tmp/main-wave-launcher/integration/wave-0.md`
-- `.tmp/main-wave-launcher/integration/wave-0.json`
-- `docs/plans/current-state.md`
-- `docs/plans/component-cutover-matrix.md`
-- `docs/plans/component-cutover-matrix.json`
-- `src/component-inventory.md`
-- `services/react-word-editor/lib/harness-config.json`
-- `services/react-word-editor/lib/harness-config.test.mjs`
-- `pnpm exec wave control status --lane main --wave 0 --json`
-
-Final closure findings:
-
-- A1 proof is satisfied in canonical status artifacts. `.tmp/main-wave-launcher/status/wave-0-0-a1.summary.json` records met proof with accepted component markers, and `.tmp/main-wave-launcher/status/wave-0-0-a1.envelope.json` matches that state.
-- A9 documentation closure is satisfied. `.tmp/main-wave-launcher/status/wave-0-0-a9.summary.json` records `docClosure.state = closed` covering `docs/plans/current-state.md`, `docs/plans/component-cutover-matrix.md`, `docs/plans/component-cutover-matrix.json`, `docs/plans/master-plan.md`, `docs/plans/migration.md`, and `docs/roadmap.md`.
-- A8 integration closure is satisfied. `.tmp/main-wave-launcher/status/wave-0-0-a8.summary.json` records `[wave-integration] state=ready-for-doc-closure claims=0 conflicts=0 blockers=0 detail=A1 proof and A9 docClosure are satisfied; A0 cont-QA rerun remains`.
-- The remaining relaunch-plan blocker is stale control-plane residue, not a product or proof gap. The last failed A0 run terminated on `Reached max turns (14)` with missing terminal marker emission, not on an unresolved architecture, integration, durability, live, or docs concern.
-
-Closure judgment:
-
-- Architecture: pass. The repository scaffold, component inventory, shared-plan docs, and service scaffolds are coherent with Wave 0 goals.
-- Integration: pass. A8's refreshed integration summary is positive and uncontradicted.
-- Durability: pass. Canonical proof artifacts and validation surfaces support the declared `inventoried` and `repo-landed` promotions.
-- Live: pass. No production deployment was required for Wave 0; local harness, validator, and wave validations are present.
-- Docs: pass. A9 closed the shared-plan documentation gate explicitly.
-
-[wave-gate] architecture=pass integration=pass durability=pass live=pass docs=pass detail=Wave-0 scaffold proof, integration, and shared-plan closure are complete; prior A0 failure was marker-emission only
-Verdict: PASS

package/docs/plans/waves/reviews/wave-1-cont-qa.md

@@ -1,46 +0,0 @@
-# Wave 1 cont-QA Report
-
-## 2026-03-26T06:07:58Z Manual Final Closure
-
-Wave 1 is ready to close. The prior stuck state was reducer and closure churn, not an unresolved contract problem.
-
-Evidence reviewed in this closure:
-
-- `docs/plans/waves/design/wave-1-a1.md`
-- `docs/plans/waves/specs/wave-1-component-boundaries.md`
-- `docs/plans/waves/specs/wave-1-runtime-contracts.md`
-- `docs/plans/waves/specs/wave-1-ooxml-contracts.md`
-- `docs/plans/waves/specs/wave-1-review-and-ui-contracts.md`
-- `docs/plans/master-plan.md`
-- `docs/plans/current-state.md`
-- `docs/plans/component-cutover-matrix.md`
-- `docs/plans/component-cutover-matrix.json`
-- `src/api/README.md`
-- `src/review/README.md`
-- `src/ui/README.md`
-- `.tmp/main-wave-launcher/integration/wave-1.md`
-- `.tmp/main-wave-launcher/integration/wave-1.json`
-- `.tmp/main-wave-launcher/status/wave-1-1-a1.summary.json`
-- `.tmp/main-wave-launcher/status/wave-1-1-a2.summary.json`
-- `.tmp/main-wave-launcher/status/wave-1-1-a3.summary.json`
-- `.tmp/main-wave-launcher/status/wave-1-1-a4.summary.json`
-- `.tmp/main-wave-launcher/proof/wave-1.json`
-
-Final closure findings:
-
-- The A2/A4 contradiction is resolved in source. `wave-1-review-and-ui-contracts.md` now adopts `RuntimeRenderSnapshot` as the only runtime-owned render contract and constrains any UI-only `EditorPresentationState` to be a derived selector rather than a competing snapshot shape.
-- The shared-plan docs are reconciled in source. `docs/plans/master-plan.md`, `docs/plans/current-state.md`, `docs/plans/component-cutover-matrix.md`, and `docs/plans/component-cutover-matrix.json` all reflect the richer canonical envelope, the external-store runtime/UI boundary, and the nine Wave 1 components at `contract-frozen`.
-- A2 and A3 already satisfied their Wave 1 proof obligations in canonical summaries.
-- A4's prior proof gap was procedural, not substantive. An authoritative proof bundle in `.tmp/main-wave-launcher/proof/wave-1.json` records the A4 contract docs and README alignments at `completion=contract durability=durable proof=unit state=met`, using the same docs-only proof bar accepted for A2 and A3.
-- No remaining Wave 1 blocker changes the Wave 2 implementation handoff.
-
-Closure judgment:
-
-- Architecture: pass. The Wave 1 contract set is internally coherent and implementation-ready.
-- Integration: pass. The owned specs, shared-plan docs, and component matrix now agree on one render boundary and one promotion state.
-- Durability: pass. The frozen contracts are durable docs with source-backed validation and an authoritative proof bundle where the prior summary drifted.
-- Live: pass. No deployment was required for Wave 1.
-- Docs: pass. Shared-plan surfaces and owned contract docs are aligned.
-
-[wave-gate] architecture=pass integration=pass durability=pass live=pass docs=pass detail=Wave-1 contract freeze is coherent and ready for Wave-2 implementation; prior blocker state was stale closure residue
-Verdict: PASS

package/docs/plans/waves/reviews/wave-10-accessibility-and-design.md

@@ -1,51 +0,0 @@
-# Wave 10 Accessibility And DESIGN Conformance Review
-
-Generated on `2026-03-27T10:10:00Z` for Wave 10 / A5.
-
-Status: `passed`
-
-This review re-checks the declared Wave 10 v1 shell against [DESIGN.md](/home/coder/docx-react-component/DESIGN.md) and the current accessibility bar without widening support into Wave 11 release-readiness or Wave 12 legal-fidelity expansion.
-
-## Evidence Reviewed
-
-- [DESIGN.md](/home/coder/docx-react-component/DESIGN.md)
-- [docs/reference/repository-guidance.md](/home/coder/docx-react-component/docs/reference/repository-guidance.md)
-- [docs/legal-feedback-architecture.md](/home/coder/docx-react-component/docs/legal-feedback-architecture.md)
-- [docs/reference/prototype-agent-prompt-legal-fidelity.md](/home/coder/docx-react-component/docs/reference/prototype-agent-prompt-legal-fidelity.md)
-- [services/react-word-editor/app/globals.css](/home/coder/docx-react-component/services/react-word-editor/app/globals.css)
-- [services/react-word-editor/lib/demo-fixtures.ts](/home/coder/docx-react-component/services/react-word-editor/lib/demo-fixtures.ts)
-- [src/ui/theme/design-tokens.ts](/home/coder/docx-react-component/src/ui/theme/design-tokens.ts)
-- [src/ui/WordReviewEditor.tsx](/home/coder/docx-react-component/src/ui/WordReviewEditor.tsx)
-- [src/ui/editor-surface/editor-surface.tsx](/home/coder/docx-react-component/src/ui/editor-surface/editor-surface.tsx)
-- [.tmp/wave-10-certification/accessibility-signoff.md](/home/coder/docx-react-component/.tmp/wave-10-certification/accessibility-signoff.md)
-- [.tmp/wave-10-certification/design-conformance.md](/home/coder/docx-react-component/.tmp/wave-10-certification/design-conformance.md)
-
-## What Changed
-
-1. Contrast-safe review tokens now clear the normal-text AA bar.
-
-- The updated token audit measures `#616161` on white at `6.19:1`, `#1660a8` on white at `6.42:1`, `#1660a8` on accent-soft at `5.69:1`, and `#7a4f00` on warning-soft at `6.44:1`.
-- Those values replace the earlier low-contrast chrome tokens that were driving the Wave 10 accessibility block.
-
-2. The prototype table story no longer overclaims live runtime support.
-
-- [services/react-word-editor/lib/demo-fixtures.ts](/home/coder/docx-react-component/services/react-word-editor/lib/demo-fixtures.ts) now frames table affordances as future runtime-backed direction and preserve-only truth instead of `Editable — supported` copy on live-path tables.
-
-3. The shipped `src/ui` shell now uses shared tokens and font roles.
-
-- [src/ui/theme/design-tokens.ts](/home/coder/docx-react-component/src/ui/theme/design-tokens.ts) centralizes the palette and typography roles.
-- A current `rg` sweep returns no literal hex or inline `rgba(...)` palette values under `src/ui`. The shadow tokens (`--color-shadow`, `--color-shadow-strong`) added in Wave 8 cleanup ensure page-mode and floating-toolbar shadows invert correctly in dark mode.
-- The main document shell now uses calmer review-facing copy and legal-font roles instead of the previous debugging-flavored runtime messaging inside the reading column.
-
-## Validation
-
-- `pnpm --dir services/react-word-editor test`
-- `pnpm --filter @docx-react-component/react-word-editor-harness build`
-
-Both commands pass on the refreshed worktree.
-
-## Conclusion
-
-Wave 10 accessibility and DESIGN conformance now pass on the current worktree.
-
-This review does not close Wave 10 overall. The remaining closure blockers are outside A5 scope: pending manual Word notes and the need to rerun the bundle on a commit-fresh tree.

package/docs/plans/waves/reviews/wave-10-cont-qa.md

@@ -1,24 +0,0 @@
-# Wave 10 Continuous QA
-
-Generated on `2026-03-27T10:10:00Z` for Wave 10 / A0.
-
-Verdict: `BLOCKED`
-
-[wave-gate] architecture=pass integration=blocked durability=blocked live=blocked docs=pass detail=Wave 10 now has a current bounded-v1 blocker set: pending manual Word notes plus the need to rerun the bundle on a commit-fresh tree.
-
-## Current Truth
-
-1. The stale blocker claims have been cleared.
-
-- `F09` and `F13` no longer fail the stored validator-backed bundle.
-- `S02` remains visible, but as explicit fail-closed proof rather than as a missing export path.
-- Accessibility, DESIGN, and performance signoff have been refreshed on the current worktree.
-
-2. The wave still cannot close yet.
-
-- Required manual Word Desktop and Word Web notes are still pending for `F01`, `F03`, `F05`, `F09`, `F11`, `F12`, `F15`, `F20`, and `S01`.
-- The current worktree is still dirty, so the bundle is not commit-fresh.
-
-## Closure Recommendation
-
-Keep Wave 10 blocked until the remaining manual notes are attached and the certification bundle is rerun on a clean commit.

package/docs/plans/waves/reviews/wave-10-dashboard-proof.md

@@ -1,46 +0,0 @@
-# Wave 10 Dashboard Proof
-
-## Scope
-
-Wave 10 Agent A3 owns the QA dashboard and release diagnostics surface for:
-
-- `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`
-
-The dashboard must derive state from durable stored artifacts, not hand-entered summaries.
-
-## Durable Inputs
-
-The implementation reads from:
-
-- `.tmp/wave-10-certification/regression-report.json`
-- `.tmp/wave-10-certification/certification-freshness.json`
-- `.tmp/wave-10-certification/fixture-coverage.json`
-- `.tmp/wave-10-certification/*-run.json`
-- the harness certification store under `services/react-word-editor/.tmp/react-word-editor-harness/certifications.json` or the configured `HARNESS_STORAGE_DIR`
-
-## Derived Proof Outputs
-
-`services/react-word-editor/lib/run-history.ts` writes these derived proof artifacts from the stored inputs above:
-
-- `.tmp/wave-10-certification/dashboard-summary.json`
-- `.tmp/wave-10-certification/run-history-check.json`
-
-These files are machine-derived summaries, not operator-authored state.
-
-## Validation
-
-Run:
-
-```bash
-pnpm --filter @docx-react-component/react-word-editor-harness test
-pnpm --filter @docx-react-component/react-word-editor-harness build
-node --input-type=module -e "import('./services/react-word-editor/lib/run-history.ts').then(async (m) => { const model = await m.getWave10DashboardModel(); console.log(JSON.stringify({ overallStatus: model.regression.overallStatus, runHistoryGaps: model.runHistory.summary.gaps, dashboardSummaryPath: model.proofArtifacts.dashboardSummaryPath, runHistoryCheckPath: model.proofArtifacts.runHistoryCheckPath }, null, 2)); })"
-```
-
-## Expected Operator Outcomes
-
-- Operators can see regression, certification freshness, validator outcomes, accessibility/design/performance signoffs, and run-history linkage in one page.
-- Preserve-only caveats and blocked exports remain visible at a glance.
-- `GET /api/runs/[runId]` returns derived diagnostics alongside the stored validator model.