@beyondwork/docx-react-component 1.0.0

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

@@ -0,0 +1,307 @@
+# 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

@@ -0,0 +1,155 @@
+# 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.