@beyondwork/docx-react-component 1.0.0 → 1.0.2

package/docs/plans/component-cutover-matrix.md

@@ -1,307 +0,0 @@
-# Component Cutover Matrix
-
-This matrix is the canonical place to answer which harness components are expected to be working at which maturity level.
-
-## Levels
-
-- `inventoried`
-- `contract-frozen`
-- `repo-landed`
-- `baseline-proved`
-- `pilot-live`
-- `qa-proved`
-- `fleet-ready`
-- `cutover-ready`
-- `deprecation-ready`
-
-## Components
-
-- `canonical-document-model`: Canonical document model
-- `command-and-transaction-runtime`: Command and transaction runtime
-- `comments-and-anchor-mapping`: Comments and anchor mapping
-- `compatibility-and-word-validation`: Compatibility and Word validation
-- `docx-export-and-serialization`: DOCX export and serialization
-- `docx-import-and-normalization`: DOCX import and normalization
-- `openxml-sdk-validator-service`: Open XML SDK validator service
-- `railway-test-harness`: Railway test harness
-- `react-editor-ui`: React editor UI
-- `tracked-changes-and-review-actions`: Tracked changes and review actions
-- `unsupported-ooxml-preservation`: Unsupported OOXML preservation
-- `table-editing`: Table editing
-- `npm-package-distribution`: npm package distribution
-- `version-compare-engine`: Version compare engine
-- `production-hardening`: Production hardening
-- `xlsx-canonical-workbook-model`: Canonical workbook model
-- `xlsx-import-and-normalization`: XLSX import and normalization
-- `xlsx-export-and-serialization`: XLSX export and serialization
-- `xlsx-command-runtime`: XLSX command and transaction runtime
-- `xlsx-grid-editor-surface`: Spreadsheet grid editor surface
-- `xlsx-fixture-corpus`: XLSX fixture corpus and certification
-- `editor-feature-parity`: Editor feature parity
-- `ooxml-property-completeness`: OOXML property completeness
-- `document-sub-parts`: Document sub-parts (headers, footers, notes)
-- `structural-block-types`: Structural block types (SDT, nested tables)
-- `track-change-extensions`: Track change extensions
-- `complex-rendering`: Complex rendering (charts, shapes, SmartArt, WordArt, VML)
-
-## Current Levels
-
-| Component | Current level | Proof surfaces |
-| --- | --- | --- |
-| `canonical-document-model` | `fleet-ready` | schema docs, canonical JSON examples, model tests |
-| `command-and-transaction-runtime` | `fleet-ready` | command tests, mapping tests, state-transition proofs |
-| `comments-and-anchor-mapping` | `baseline-proved` | anchor remap tests, threaded comment fixtures, review model docs |
-| `compatibility-and-word-validation` | `fleet-ready` | feature matrix, compatibility tests, Word reopen evidence |
-| `docx-export-and-serialization` | `fleet-ready` | round-trip fixtures, export validation tests, serializer docs |
-| `docx-import-and-normalization` | `fleet-ready` | .docx import fixtures, normalization tests, supported-feature mapping docs |
-| `openxml-sdk-validator-service` | `pilot-live` | service scaffold, validator endpoint contract, Docker packaging, local smoke proof, CI-wired pilot bundle |
-| `railway-test-harness` | `repo-landed` | service scaffold, Railway docs, local harness build/test proof, pending private redeploy artifact bundle |
-| `react-editor-ui` | `fleet-ready` | component tests, selection behavior checks, review-surface checks, token and theme checks |
-| `tracked-changes-and-review-actions` | `baseline-proved` | revision fixtures, accept/reject tests, review-state mapping tests, preserve-only review-boundary proof (.tmp/wave-7-preservation/review-boundary-report.json) |
-| `unsupported-ooxml-preservation` | `fleet-ready` | preservation fixtures (F15-F21), fragment retention tests, export reattachment tests, package-fidelity proof (.tmp/wave-7-preservation/), malformed-doc diagnostics tests |
-| `table-editing` | `baseline-proved` | table schema and command tests, table round-trip fixtures, .tmp/wave-20-table-proof/ |
-| `npm-package-distribution` | `inventoried` | tests |
-| `version-compare-engine` | `inventoried` | tests |
-| `production-hardening` | `inventoried` | tests |
-| `xlsx-canonical-workbook-model` | `baseline-proved` | workbook model tests, cell value type tests, merge range tracking tests, .tmp/wave-25-xlsx-proof/model-tests.json |
-| `xlsx-import-and-normalization` | `baseline-proved` | SpreadsheetML import tests, shared strings resolution tests, .tmp/wave-25-xlsx-proof/import-tests.json |
-| `xlsx-export-and-serialization` | `inventoried` | tests |
-| `xlsx-command-runtime` | `inventoried` | tests |
-| `xlsx-grid-editor-surface` | `inventoried` | tests |
-| `xlsx-fixture-corpus` | `inventoried` | tests |
-| `editor-feature-parity` | `baseline-proved` | formatting mark tests, image command tests, search plugin tests, useDocxEditor hook tests, CLI tests, .tmp/wave-28-parity-proof/ |
-| `ooxml-parsing-fidelity` | `baseline-proved` | paragraph/run property round-trip tests, table property round-trip tests, fields-bookmarks tests, .tmp/wave-29-parsing-proof/ |
-| `ooxml-property-completeness` | `baseline-proved` | property-completeness round-trip tests (test/io/property-completeness.test.ts), .tmp/wave-32-props-proof/all-props.json |
-| `document-sub-parts` | `baseline-proved` | header/footer round-trip tests (test/io/headers-footers-roundtrip.test.ts), footnote/endnote round-trip tests (test/io/footnotes-roundtrip.test.ts), theme parse and package-preservation proof (.tmp/wave-33-subparts-proof/all-subparts.json) |
-| `structural-block-types` | `baseline-proved` | structural block round-trip tests (test/io/structural-blocks.test.ts), text round-trip regression tests (test/io/text-roundtrip.test.ts), table schema regression tests (test/runtime/table-schema.test.ts), .tmp/wave-34-blocks-proof/structural.json |
-| `track-change-extensions` | `baseline-proved` | property change revision tests (test/review/property-change-revisions.test.ts), move revision tests (test/review/move-revisions.test.ts), sectPrChange/tblPrChange accept/reject coverage, pPrChange preserve-only with PropertyChangeData, moveFrom/moveTo linked move ID pairing, .tmp/wave-35-track-proof/revisions.json |
-| `complex-rendering` | `baseline-proved` | complex content round-trip tests (test/io/complex-content-roundtrip.test.ts), ChartPreviewNode/SmartArtPreviewNode/ShapeNode/WordArtNode/VmlShapeNode canonical types with rawXml, opaque_inline surface projection with labeled preview atoms, .tmp/wave-36-complex-proof/all-complex.json |
-
-## Promotions By Wave
-
-### Wave 0
-
-- Wave 0 promotes `canonical-document-model` to `baseline-proved`.
-- Wave 0 promotes `command-and-transaction-runtime` to `baseline-proved`.
-- Wave 0 promotes `comments-and-anchor-mapping` to `baseline-proved`.
-- Wave 0 promotes `compatibility-and-word-validation` to `baseline-proved`.
-- Wave 0 promotes `docx-export-and-serialization` to `baseline-proved`.
-- Wave 0 promotes `docx-import-and-normalization` to `baseline-proved`.
-- Wave 0 promotes `openxml-sdk-validator-service` to `baseline-proved`.
-- Wave 0 promotes `railway-test-harness` to `repo-landed`.
-- Wave 0 promotes `react-editor-ui` to `baseline-proved`.
-- Wave 0 promotes `tracked-changes-and-review-actions` to `baseline-proved`.
-- Wave 0 promotes `unsupported-ooxml-preservation` to `baseline-proved`.
-
-### Wave 1
-
-- Wave 1 promotes `canonical-document-model` to `baseline-proved`.
-- Wave 1 promotes `command-and-transaction-runtime` to `baseline-proved`.
-- Wave 1 promotes `comments-and-anchor-mapping` to `baseline-proved`.
-- Wave 1 promotes `compatibility-and-word-validation` to `baseline-proved`.
-- Wave 1 promotes `docx-export-and-serialization` to `baseline-proved`.
-- Wave 1 promotes `docx-import-and-normalization` to `baseline-proved`.
-- Wave 1 promotes `react-editor-ui` to `baseline-proved`.
-- Wave 1 promotes `tracked-changes-and-review-actions` to `baseline-proved`.
-- Wave 1 promotes `unsupported-ooxml-preservation` to `baseline-proved`.
-
-### Wave 2
-
-- Wave 2 promotes `canonical-document-model` to `baseline-proved`.
-- Wave 2 promotes `command-and-transaction-runtime` to `baseline-proved`.
-- Wave 2 promotes `docx-export-and-serialization` to `baseline-proved`.
-- Wave 2 promotes `docx-import-and-normalization` to `baseline-proved`.
-- Wave 2 promotes `react-editor-ui` to `baseline-proved`.
-
-### Wave 3
-
-- Wave 3 promotes `canonical-document-model` to `baseline-proved`.
-- Wave 3 promotes `command-and-transaction-runtime` to `baseline-proved`.
-- Wave 3 promotes `compatibility-and-word-validation` to `baseline-proved`.
-- Wave 3 promotes `docx-export-and-serialization` to `baseline-proved`.
-- Wave 3 promotes `docx-import-and-normalization` to `baseline-proved`.
-- Wave 3 promotes `openxml-sdk-validator-service` to `baseline-proved`.
-- Wave 3 promotes `react-editor-ui` to `baseline-proved`.
-
-### Wave 4
-
-- Wave 4 promotes `comments-and-anchor-mapping` to `baseline-proved`.
-- Wave 4 promotes `compatibility-and-word-validation` to `baseline-proved`.
-- Wave 4 promotes `unsupported-ooxml-preservation` to `baseline-proved`.
-
-### Wave 5
-
-- Wave 5 promotes `comments-and-anchor-mapping` to `baseline-proved`.
-- Wave 5 promotes `compatibility-and-word-validation` to `baseline-proved`.
-- Wave 5 promotes `tracked-changes-and-review-actions` to `baseline-proved`.
-
-### Wave 6
-
-- Wave 6 promotes `tracked-changes-and-review-actions` to `baseline-proved`.
-- Wave 6 promotes `unsupported-ooxml-preservation` to `baseline-proved`.
-
-### Wave 7
-
-- Wave 7 promotes `tracked-changes-and-review-actions` to `baseline-proved`.
-- Wave 7 promotes `unsupported-ooxml-preservation` to `baseline-proved`.
-
-### Wave 8
-
-- Wave 8 promotes `openxml-sdk-validator-service` to `pilot-live`.
-- Wave 8 promotes `railway-test-harness` to `baseline-proved`.
-
-### Wave 9
-
-- Wave 9 promotes `canonical-document-model` to `pilot-live`.
-- Wave 9 promotes `command-and-transaction-runtime` to `pilot-live`.
-- Wave 9 promotes `comments-and-anchor-mapping` to `pilot-live`.
-- Wave 9 promotes `compatibility-and-word-validation` to `pilot-live`.
-- Wave 9 promotes `docx-export-and-serialization` to `pilot-live`.
-- Wave 9 promotes `docx-import-and-normalization` to `pilot-live`.
-- Wave 9 promotes `railway-test-harness` to `pilot-live`.
-- Wave 9 promotes `react-editor-ui` to `pilot-live`.
-- Wave 9 promotes `tracked-changes-and-review-actions` to `pilot-live`.
-- Wave 9 promotes `unsupported-ooxml-preservation` to `pilot-live`.
-
-### Wave 10
-
-- Wave 10 promotes `canonical-document-model` to `qa-proved`.
-- Wave 10 promotes `command-and-transaction-runtime` to `qa-proved`.
-- Wave 10 promotes `comments-and-anchor-mapping` to `qa-proved`.
-- Wave 10 promotes `compatibility-and-word-validation` to `qa-proved`.
-- Wave 10 promotes `docx-export-and-serialization` to `qa-proved`.
-- Wave 10 promotes `docx-import-and-normalization` to `qa-proved`.
-- Wave 10 promotes `openxml-sdk-validator-service` to `qa-proved`.
-- Wave 10 promotes `railway-test-harness` to `qa-proved`.
-- Wave 10 promotes `react-editor-ui` to `qa-proved`.
-- Wave 10 promotes `tracked-changes-and-review-actions` to `qa-proved`.
-- Wave 10 promotes `unsupported-ooxml-preservation` to `qa-proved`.
-
-### Wave 11
-
-- Wave 11 promotes `canonical-document-model` to `fleet-ready`.
-- Wave 11 promotes `command-and-transaction-runtime` to `fleet-ready`.
-- Wave 11 promotes `comments-and-anchor-mapping` to `fleet-ready`.
-- Wave 11 promotes `compatibility-and-word-validation` to `fleet-ready`.
-- Wave 11 promotes `docx-export-and-serialization` to `fleet-ready`.
-- Wave 11 promotes `docx-import-and-normalization` to `fleet-ready`.
-- Wave 11 promotes `openxml-sdk-validator-service` to `fleet-ready`.
-- Wave 11 promotes `railway-test-harness` to `fleet-ready`.
-- Wave 11 promotes `react-editor-ui` to `fleet-ready`.
-- Wave 11 promotes `tracked-changes-and-review-actions` to `fleet-ready`.
-- Wave 11 promotes `unsupported-ooxml-preservation` to `fleet-ready`.
-
-### Wave 12
-
-- Wave 12 promotes `canonical-document-model` to `fleet-ready`.
-- Wave 12 promotes `command-and-transaction-runtime` to `fleet-ready`.
-- Wave 12 promotes `comments-and-anchor-mapping` to `fleet-ready`.
-- Wave 12 promotes `compatibility-and-word-validation` to `fleet-ready`.
-- Wave 12 promotes `docx-export-and-serialization` to `fleet-ready`.
-- Wave 12 promotes `docx-import-and-normalization` to `fleet-ready`.
-- Wave 12 promotes `react-editor-ui` to `fleet-ready`.
-- Wave 12 promotes `tracked-changes-and-review-actions` to `fleet-ready`.
-- Wave 12 promotes `unsupported-ooxml-preservation` to `fleet-ready`.
-
-### Wave 13
-
-- Wave 13 promotes `canonical-document-model` to `fleet-ready`.
-- Wave 13 promotes `command-and-transaction-runtime` to `fleet-ready`.
-- Wave 13 promotes `docx-export-and-serialization` to `fleet-ready`.
-- Wave 13 promotes `docx-import-and-normalization` to `fleet-ready`.
-- Wave 13 promotes `react-editor-ui` to `fleet-ready`.
-
-### Wave 14
-
-- Wave 14 promotes `canonical-document-model` to `fleet-ready`.
-- Wave 14 promotes `command-and-transaction-runtime` to `baseline-proved`.
-- Wave 14 promotes `compatibility-and-word-validation` to `fleet-ready`.
-- Wave 14 promotes `docx-export-and-serialization` to `fleet-ready`.
-- Wave 14 promotes `docx-import-and-normalization` to `fleet-ready`.
-- Wave 14 promotes `react-editor-ui` to `fleet-ready`.
-
-### Wave 15
-
-- Wave 15 promotes `command-and-transaction-runtime` to `fleet-ready`.
-- Wave 15 promotes `compatibility-and-word-validation` to `fleet-ready`.
-- Wave 15 promotes `docx-export-and-serialization` to `fleet-ready`.
-- Wave 15 promotes `docx-import-and-normalization` to `fleet-ready`.
-- Wave 15 promotes `react-editor-ui` to `fleet-ready`.
-
-### Wave 16
-
-- Wave 16 promotes `command-and-transaction-runtime` to `baseline-proved`.
-- Wave 16 promotes `compatibility-and-word-validation` to `fleet-ready`.
-- Wave 16 promotes `docx-export-and-serialization` to `fleet-ready`.
-- Wave 16 promotes `docx-import-and-normalization` to `fleet-ready`.
-- Wave 16 promotes `react-editor-ui` to `fleet-ready`.
-- Wave 16 promotes `unsupported-ooxml-preservation` to `fleet-ready`.
-
-### Wave 17
-
-- Wave 17 promotes `command-and-transaction-runtime` to `baseline-proved`.
-- Wave 17 promotes `comments-and-anchor-mapping` to `fleet-ready`.
-- Wave 17 promotes `compatibility-and-word-validation` to `fleet-ready`.
-- Wave 17 promotes `docx-export-and-serialization` to `fleet-ready`.
-- Wave 17 promotes `docx-import-and-normalization` to `fleet-ready`.
-- Wave 17 promotes `react-editor-ui` to `fleet-ready`.
-- Wave 17 promotes `tracked-changes-and-review-actions` to `fleet-ready`.
-- Wave 17 promotes `unsupported-ooxml-preservation` to `fleet-ready`.
-
-### Wave 18
-
-- Wave 18 promotes `canonical-document-model` to `fleet-ready`.
-- Wave 18 promotes `command-and-transaction-runtime` to `fleet-ready`.
-- Wave 18 promotes `compatibility-and-word-validation` to `fleet-ready`.
-- Wave 18 promotes `docx-export-and-serialization` to `fleet-ready`.
-- Wave 18 promotes `docx-import-and-normalization` to `fleet-ready`.
-- Wave 18 promotes `react-editor-ui` to `fleet-ready`.
-- Wave 18 promotes `unsupported-ooxml-preservation` to `fleet-ready`.
-
-### Wave 19
-
-- Wave 19 promotes `openxml-sdk-validator-service` to `pilot-live`.
-
-### Wave 20
-
-- Wave 20 promotes `table-editing` to `baseline-proved`.
-
-### Wave 25
-
-- Wave 25 promotes `xlsx-canonical-workbook-model` to `baseline-proved`.
-- Wave 25 promotes `xlsx-import-and-normalization` to `baseline-proved`.
-
-### Wave 28
-
-- Wave 28 promotes `editor-feature-parity` to `baseline-proved`.
-
-### Wave 29
-
-- Wave 29 promotes `ooxml-parsing-fidelity` to `baseline-proved`.
-
-### Wave 32
-
-- Wave 32 promotes `ooxml-property-completeness` to `baseline-proved`.
-
-### Wave 33
-
-- Wave 33 promotes `document-sub-parts` to `baseline-proved`.
-
-### Wave 34
-
-- Wave 34 promotes `structural-block-types` to `baseline-proved`.
-
-### Wave 35
-
-- Wave 35 promotes `track-change-extensions` to `baseline-proved`.
-
-### Wave 36
-
-- Wave 36 promotes `complex-rendering` to `baseline-proved`.
-
-## Usage
-
-- Keep architecture and repository guidance docs descriptive.
-- Keep wave-by-wave component maturity and promotion targets here.
-- `currentLevel` is the canonical post-wave state of the repo, not a future plan.
-- When component promotion gating is active, wave files must match this matrix exactly.

package/docs/plans/context7-wave-orchestrator.md

@@ -1,155 +0,0 @@
-# Context7 and Wave Orchestrator
-
-See also [concepts/context7-vs-skills.md](../concepts/context7-vs-skills.md) for how Context7 differs from the repo-owned skill system.
-
-Context7 is for external library truth. Repository docs and source are for repository truth.
-
-The one deliberate exception in this repo is the planner corpus under
-`docs/context7/planner-agent/`: it is a tracked export of selected local
-planning research that the operator can publish as a custom Context7 library for
-the agentic planner.
-
-## Rules
-
-- Prefer a narrow bundle per agent or wave.
-- Keep bundle defaults and agent overrides aligned with the components the wave is promoting.
-- Do not load broad external docs by default.
-- Treat prefetched Context7 text as non-canonical prompt context.
-- Keep Context7 bundle definitions in `docs/context7/bundles.json`.
-- Launcher-side prefetch writes only to ignored cache paths under `.tmp/`.
-
-## Setup
-
-1. Add `CONTEXT7_API_KEY` to `.env.local` at repo root.
-2. Export it before launching the wave runner or any executor directly:
-
-```bash
-source scripts/context7-export-env.sh
-```
-
-3. Verify the key:
-
-```bash
-pnpm context7:api-check
-```
-
-4. Review [docs/context7/bundles.json](../context7/bundles.json) and trim it to the external libraries your repository actually uses.
-5. Prefer exact `libraryId` values. Use `libraryName` only during one-off discovery, then replace it with the pinned id returned by Context7 before committing the bundle.
-
-## Planner Bundle
-
-The shipped bundle index includes `planner-agentic`, but it is intentionally a
-local-only placeholder by default.
-
-The source files for that library live under `docs/context7/planner-agent/`.
-Refresh that folder from the ignored agent-context cache with:
-
-```bash
-pnpm research:sync-planner-context7
-```
-
-After you publish the folder to Context7, replace the placeholder bundle entry
-with the exact published `libraryId`. Do not commit a guessed `libraryName`.
-
-## Resolution Order
-
-1. Agent `### Context7`
-2. Wave `## Context7 defaults`
-3. Lane default from `docs/context7/bundles.json`
-4. `none`
-
-## Bundle Authoring
-
-Each bundle should be small and task-shaped. Prefer exact `libraryId` values and
-add a `queryHint` to keep fetched docs focused.
-
-Example:
-
-```json
-{
-  "bundles": {
-    "node-typescript": {
-      "description": "Node.js and TypeScript runtime docs.",
-      "libraries": [
-        {
-          "libraryId": "/nodejs/node",
-          "queryHint": "child processes, streams, filesystem, process lifecycle"
-        },
-        {
-          "libraryId": "/microsoft/typescript",
-          "queryHint": "module resolution, declarations, compiler behavior"
-        }
-      ]
-    }
-  }
-}
-```
-
-Keep the `none` bundle defined so agents and waves can opt out explicitly.
-
-## Wave Authoring
-
-Wave-level default:
-
-````md
-## Context7 defaults
-
-- bundle: node-typescript
-- query: "Node process spawning and test execution"
-````
-
-Agent-level override:
-
-````md
-### Context7
-
-- bundle: node-typescript
-- query: "TypeScript declarations and module resolution"
-````
-
-## Injection
-
-When a bundle is active, the launcher injects:
-
-- the resolved bundle id
-- the resolved query focus
-- the allowed library list
-- prefetched third-party snippets when available
-
-The injected block appears before the assigned implementation prompt and is labeled non-canonical. This injection is executor-agnostic.
-
-Wave coordination state is injected separately from Context7:
-
-- a compiled shared summary from `.tmp/<lane>-wave-launcher/inboxes/wave-<n>/shared-summary.md`
-- a compiled per-agent inbox from `.tmp/<lane>-wave-launcher/inboxes/wave-<n>/<agent-id>.md`
-
-Those inbox artifacts are repository-state summaries. Context7 stays reserved for third-party library truth.
-
-## Runtime Behavior
-
-- Prefetch happens in the launcher before the agent session starts.
-- Shared summary and per-agent inbox compilation also happen in the launcher before the executor is invoked.
-- Cache files are written under `.tmp/<lane>-wave-launcher/context7-cache/`.
-- Compiled inboxes are written under `.tmp/<lane>-wave-launcher/inboxes/`.
-- Executor runtime overlays are written under `.tmp/<lane>-wave-launcher/executors/`.
-- The resolved Context7 selection becomes part of the prompt fingerprint, so changing bundle or query invalidates prior success reuse.
-- If `CONTEXT7_API_KEY` is missing, prefetch is disabled with a warning and the wave continues.
-- If the Context7 API errors, the launcher fails open and starts the agent without the injected snippets.
-- Use `--no-context7` when you want to force repository-only context for a run.
-
-## Prompt Layering
-
-- `codex`
-  The generated task prompt already contains the compiled shared summary, the compiled agent inbox, and the injected Context7 block. It is piped directly into `codex exec`.
-- `claude`
-  The generated task prompt contains the compiled shared summary, the compiled agent inbox, and the injected Context7 block. The harness also writes a runtime system-prompt overlay and passes it with `--append-system-prompt-file` by default, or `--system-prompt-file` if `executors.claude.appendSystemPromptMode` is set to `replace`.
-- `opencode`
-  The generated task prompt contains the compiled shared summary, the compiled agent inbox, and the injected Context7 block. The harness writes a temporary `opencode.json` plus an agent prompt file under `.tmp/.../executors/`, points `OPENCODE_CONFIG` at that overlay, and launches `opencode run`.
-
-## Guidance
-
-- Use Context7 for external library truth, setup syntax, SDK details, and version-specific API behavior.
-- Do not use Context7 for repository architecture, plan decisions, ownership rules, or internal contracts.
-- Prefer one active backend family in a bundle instead of mixing competing frameworks.
-- Keep queries specific enough that the prefetched block stays small and useful.
-- Run `pnpm context7:api-check` after editing bundle ids to verify every pinned library still resolves and returns promptable context.