@beyondwork/docx-react-component 1.0.0 → 1.0.2

package/docs/plans/examples/wave-example-live-proof.md

@@ -1,435 +0,0 @@
-# Wave 14 - Example Full Modern Release Surface
-
-This is a showcase-first sample wave.
-
-Use it as the single reference example for the current `0.8.5` Wave surface.
-
-It intentionally combines more sections than a normal production wave so one file can demonstrate:
-
-- standard closure roles (`A0`, `E0`, `A8`, `A9`)
-- `## Eval targets` with delegated and pinned benchmark selection
-- richer `### Executor` blocks, budgets, and sticky retry
-- `### Skills`
-- `### Capabilities`
-- `### Deliverables`
-- `### Exit contract`
-- proof-first live validation with `### Proof artifacts`
-- `## Deploy environments`
-- infra and deploy-verifier specialists
-
-This example is intentionally denser than a launch-minimal wave. Its job is to teach the full authored surface in one place.
-
-**Commit message**: `Docs: add full modern sample wave`
-
-## Component promotions
-
-- learning-memory-action-plane: pilot-live
-- executor-abstraction-and-prompt-transport: baseline-proved
-
-## Deploy environments
-
-- prod: kubernetes default (primary production cluster)
-- staging: custom-deploy (manual preflight and recovery flow)
-
-## Eval targets
-
-- id: live-proof-fidelity | selection: delegated | benchmark-family: blackboard-fidelity | objective: Preserve machine-visible live proof through summaries, inboxes, and integration closure | threshold: Critical live-proof facts remain visible through final closure
-- id: contradiction-recovery | selection: pinned | benchmarks: claim-conflict-detection,evidence-based-repair | objective: Surface and repair conflicting live claims before PASS | threshold: Material contradictions become explicit repair work before final closure
-- id: silo-escape | selection: delegated | benchmark-family: silo-escape | objective: Reconstruct the correct global state from distributed live and repo evidence | threshold: Integration closure reflects the full cross-agent state instead of partial local views
-
-## Context7 defaults
-
-- bundle: node-typescript
-- query: "Orchestration state machines, retry policy, summary fidelity, and durable validation for coding agents"
-
-## Agent A0: cont-QA
-
-### Role prompts
-
-- docs/agents/wave-cont-qa-role.md
-
-### Executor
-
-- id: claude
-- model: claude-sonnet-4-6
-- claude.allowed_tools: Read,Glob
-
-### Context7
-
-- bundle: none
-
-### Prompt
-
-```text
-Primary goal:
-- Treat live proof as a real closure input, not as a narrative claim.
-
-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/migration.md.
-
-Specific expectations:
-- do not PASS unless the declared proof artifacts exist locally
-- do not infer host truth from stale repo-local snapshots
-- rely on the declared proof bundle, integration summary, and doc closure state
-
-File ownership (only touch these paths):
-- docs/plans/waves/reviews/wave-14-cont-qa.md
-```
-
-## Agent E0: cont-EVAL
-
-### Role prompts
-
-- docs/agents/wave-cont-eval-role.md
-
-### Executor
-
-- id: claude
-- model: claude-sonnet-4-6
-- claude.allowed_tools: Read,Glob
-- claude.output_format: json
-
-### Context7
-
-- bundle: none
-
-### Skills
-
-- role-cont-eval
-
-### Prompt
-
-```text
-Primary goal:
-- Evaluate whether the wave actually preserves, integrates, and repairs distributed live-proof evidence before closure.
-
-Required context before coding:
-- Read docs/reference/repository-guidance.md.
-- Read docs/research/agent-context-sources.md.
-- Read docs/evals/README.md.
-- Read docs/reference/live-proof-waves.md.
-- Read docs/plans/master-plan.md, docs/plans/current-state.md, and docs/plans/migration.md.
-
-Specific expectations:
-- for delegated targets, choose the smallest benchmark set that genuinely exercises the failure mode
-- for pinned targets, run the exact benchmark ids named in the wave contract
-- record the exact selected target ids and benchmark ids in the append-only report
-
-File ownership (only touch these paths):
-- docs/plans/waves/reviews/wave-14-cont-eval.md
-```
-
-## Agent A8: Integration Steward
-
-### Role prompts
-
-- docs/agents/wave-integration-role.md
-
-### Executor
-
-- id: claude
-- model: claude-sonnet-4-6
-
-### Context7
-
-- bundle: none
-
-### Capabilities
-
-- integration
-- live-proof-reconciliation
-- contradiction-recovery
-- blackboard-fidelity
-
-### Prompt
-
-```text
-Primary goal:
-- Reconcile repo changes, proof artifacts, infra state, and deploy-verifier evidence into one closure-ready decision.
-
-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 and docs/plans/current-state.md.
-
-Specific expectations:
-- treat missing proof artifacts as blocking
-- prefer explicit follow-up requests over vague warnings
-- call out stale or contradictory live-proof claims
-- use the `cont-EVAL` report and exact benchmark ids as evidence, not as a suggestion
-
-File ownership (only touch these paths):
-- .tmp/main-wave-launcher/integration/wave-14.md
-- .tmp/main-wave-launcher/integration/wave-14.json
-```
-
-## Agent A9: Documentation Steward
-
-### Role prompts
-
-- docs/agents/wave-documentation-role.md
-
-### Executor
-
-- profile: docs-pass
-
-### Context7
-
-- bundle: none
-
-### Prompt
-
-```text
-Primary goal:
-- Keep shared-plan docs and release-facing notes aligned with the proof-first live workflow.
-
-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/migration.md.
-
-File ownership (only touch these paths):
-- docs/plans/current-state.md
-- docs/plans/master-plan.md
-- docs/plans/migration.md
-- docs/evals/README.md
-```
-
-## Agent A1: Runtime And Summary Hardening
-
-### Executor
-
-- profile: implement-fast
-- model: gpt-5-codex
-- codex.config: model_reasoning_effort=high
-- codex.search: true
-- codex.json: true
-- codex.add_dirs: docs,scripts,test
-- fallbacks: claude, opencode
-- budget.minutes: 45
-
-### Context7
-
-- bundle: node-typescript
-- query: "Retry orchestration, summary integrity, validation rules, and Vitest coverage for agent systems"
-
-### Skills
-
-- role-implementation
-- runtime-codex
-- repo-coding-rules
-
-### Components
-
-- executor-abstraction-and-prompt-transport
-
-### Capabilities
-
-- status-reconciliation
-- benchmark-integration
-- summary-fidelity
-
-### Exit contract
-
-- completion: integrated
-- durability: durable
-- proof: integration
-- doc-impact: owned
-
-### Deliverables
-
-- scripts/wave-orchestrator/launcher.mjs
-- scripts/wave-orchestrator/coordination-store.mjs
-- test/wave-orchestrator/launcher.test.ts
-- test/wave-orchestrator/coordination-store.test.ts
-
-### Prompt
-
-```text
-Primary goal:
-- Tighten the runtime's handling of retries, summaries, and benchmark-facing evidence so proof-centric closure stays machine-visible.
-
-Required context before coding:
-- Read docs/reference/repository-guidance.md.
-- Read docs/research/agent-context-sources.md.
-- Read docs/evals/README.md.
-- Read docs/reference/live-proof-waves.md.
-- Read docs/plans/current-state.md and docs/plans/wave-orchestrator.md.
-
-Specific expectations:
-- preserve prompt-hash-based reuse safety
-- keep distributed evidence visible through the shared summary and inbox layers
-- add or update regression coverage for any retry or summary behavior you change
-
-File ownership (only touch these paths):
-- scripts/wave-orchestrator/launcher.mjs
-- scripts/wave-orchestrator/coordination-store.mjs
-- test/wave-orchestrator/launcher.test.ts
-- test/wave-orchestrator/coordination-store.test.ts
-```
-
-## Agent A6: Learning Plane Live Validation
-
-### Executor
-
-- id: codex
-- retry-policy: sticky
-- budget.minutes: 30
-- codex.search: true
-- codex.json: true
-
-### Context7
-
-- bundle: none
-
-### Skills
-
-- role-infra
-- provider-kubernetes
-- provider-custom-deploy
-
-### Components
-
-- learning-memory-action-plane
-
-### Capabilities
-
-- live-proof
-- restart-safety
-- deploy-validation
-
-### Exit contract
-
-- completion: live
-- durability: durable
-- proof: live
-- doc-impact: owned
-
-### Deliverables
-
-- docs/plans/waves/reviews/wave-14-live-proof.md
-
-### Proof artifacts
-
-- path: .tmp/wave-14-learning-proof/learning-dry-run-status.json | kind: live-status | required-for: pilot-live
-- path: .tmp/wave-14-learning-proof/learning-plane-before-restart.json | kind: live-status | required-for: pilot-live
-- path: .tmp/wave-14-learning-proof/learning-plane-after-restart.json | kind: restart-check | required-for: pilot-live
-- path: .tmp/wave-14-learning-proof/learning-vector-manifest.json | kind: manifest | required-for: pilot-live
-
-### Prompt
-
-```text
-Primary goal:
-- Capture restart-safe learning-plane proof as a local machine-visible bundle and write the review note that closure roles will trust.
-
-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/wave-orchestrator.md.
-
-Operator command sequence:
-- leapctl learning status --json > .tmp/wave-14-learning-proof/learning-plane-before-restart.json
-- leapctl learning dry-run --json > .tmp/wave-14-learning-proof/learning-dry-run-status.json
-- leapctl learning restart --env prod
-- leapctl learning status --json > .tmp/wave-14-learning-proof/learning-plane-after-restart.json
-- leapctl learning manifest --json > .tmp/wave-14-learning-proof/learning-vector-manifest.json
-
-Specific expectations:
-- closure only counts when the declared proof artifacts exist locally
-- if live host state and cached state disagree, prefer current control-plane truth and log the discrepancy explicitly
-- if proof arrives after a failed attempt, expect a targeted rerun on the same executor instead of generic fallback
-- post exact artifact paths and machine-visible evidence through coordination instead of assuming closure agents will rediscover host state
-
-File ownership (only touch these paths):
-- .tmp/wave-14-learning-proof/
-- docs/plans/waves/reviews/wave-14-live-proof.md
-```
-
-## Agent A7: Infra Proof Steward
-
-### Role prompts
-
-- docs/agents/wave-infra-role.md
-
-### Executor
-
-- id: opencode
-- opencode.format: json
-- opencode.steps: 12
-
-### Context7
-
-- bundle: none
-
-### Skills
-
-- role-infra
-- provider-kubernetes
-
-### Prompt
-
-```text
-Primary goal:
-- Verify infra and workload identity assumptions around the live proof owner's commands.
-
-Required context before coding:
-- Read docs/reference/repository-guidance.md.
-- Read docs/research/agent-context-sources.md.
-- Read docs/reference/live-proof-waves.md.
-
-Specific expectations:
-- emit infra markers instead of vague prose
-- call out drift or setup-required states explicitly
-- open targeted follow-up work if the live proof owner depends on unresolved infra setup
-
-File ownership (only touch these paths):
-- .tmp/main-wave-launcher/logs/wave-14-a7.log
-```
-
-## Agent D1: Deploy Verifier
-
-### Role prompts
-
-- docs/agents/wave-deploy-verifier-role.md
-
-### Executor
-
-- id: opencode
-- opencode.format: json
-- opencode.steps: 10
-
-### Context7
-
-- bundle: none
-
-### Skills
-
-- role-deploy
-- provider-kubernetes
-- provider-custom-deploy
-
-### Prompt
-
-```text
-Primary goal:
-- Verify that the rollout associated with the live proof owner is healthy enough to preserve the `pilot-live` claim.
-
-Required context before coding:
-- Read docs/reference/repository-guidance.md.
-- Read docs/research/agent-context-sources.md.
-- Read docs/reference/live-proof-waves.md.
-
-Specific expectations:
-- use explicit deploy status markers for healthy, failed, or rolled-over states
-- do not sign off on implied host health
-- if rollout evidence is incomplete, leave an explicit deploy-risk trail for integration and cont-QA
-
-File ownership (only touch these paths):
-- .tmp/main-wave-launcher/logs/wave-14-d1.log
-```

package/docs/plans/master-plan.md

@@ -1,224 +0,0 @@
-# Master Plan
-
-## Objective
-
-Reframe this repository as `react-ooxml-office`: a fidelity-first office-document repo with:
-
-- a shared OOXML platform layer
-- format-specific runtimes
-- host-facing editor surfaces
-
-The current shipped implementation remains the docx editor behind `WordReviewEditor`. The broader plan must stay honest about that current reality while making room for xlsx and later future verticals.
-
-## Locked Repo Decisions
-
-- The only shipped public component today is `WordReviewEditor`.
-- The current landed runtime is docx-specific and remains the active implementation track.
-- `xlsx` is the next planned OOXML sibling and should reuse shared platform work without inheriting docx-specific runtime or UI assumptions.
-- `pdf` is future work and is not part of the first shared OOXML platform contract.
-- Shipped runtimes remain main-thread only unless the architecture explicitly changes.
-- The Microsoft Open XML SDK remains validation-only in CI or service contexts, never the shipped browser transformation engine.
-
-## Layered Architecture
-
-The repo should be read in three layers.
-
-### 1. Shared Platform
-
-Owns what should remain common across OOXML siblings:
-
-- OPC package reading and writing
-- part manifests, content types, and relationship integrity
-- preserved-part capture and reattachment
-- compatibility vocabulary and export blockers
-- validator-service integration
-- host persistence, snapshot, and event doctrine
-- future shared agent or AI mediation boundaries
-
-### 2. Format Runtimes
-
-Own format-specific canonical models, commands, and projections:
-
-- `docx`: document model, review model, Word compatibility, current `WordReviewEditor`
-- `xlsx`: workbook model, range and formula semantics, spreadsheet-native UI
-- `pdf`: future, outside the first OOXML platform layer
-
-### 3. Host Surfaces
-
-Own the embeddable editor shell, internal harnesses, certification routes, and host integration docs.
-
-## Current Source Truth
-
-The landed source tree remains docx-first:
-
-```text
-src/
-  api/
-  model/
-  core/
-  review/
-  io/
-  preservation/
-  validation/
-  runtime/
-  ui/
-services/
-  react-word-editor/
-  openxml-validator/
-```
-
-This remains the truthful source layout for implementation work today.
-
-## Target Source Direction
-
-The broader target source layout is:
-
-```text
-src/
-  platform/
-  formats/
-    docx/
-    xlsx/
-    pdf/
-services/
-  office-harness/
-  openxml-validator/
-```
-
-This is a target-state planning direction only. It must not be treated as already landed code.
-
-## Current Shipped Docx Contract
-
-The current public and fidelity contracts remain docx-specific:
-
-- public API: `docs/reference/public-api.md`
-- compliance and validation: `docs/reference/ooxml-compliance.md`
-- frontend architecture: `docs/reference/word-review-editor-frontend-architecture.md`
-- UX guide: `docs/reference/word-review-editor-ux-guide.md`
-
-Current product doctrine for the shipped editor remains:
-
-- runtime-owned canonical state
-- commands and transactions as the only mutation path
-- preserve-only handling for unsupported but preservable OOXML
-- Word reopen behavior as the final certification bar
-- calm, review-oriented UI rather than ribbon-style chrome
-
-## Active Docx Implementation Track
-
-The current maturity line is still the docx Wave sequence.
-
-### Bounded v1 Waves (`wave-0` to `wave-11`)
-
-- `wave-0` to `wave-1`: framing, contracts, fixture program, and ownership boundaries
-- `wave-2` to `wave-7`: landed runtime, editing, review, preservation, and compatibility substrate
-- `wave-8` to `wave-10`: harness, certification, accessibility, and performance proof
-- `wave-11`: fleet-ready packaging, demo posture, and release documentation
-
-Current status:
-
-- the current Wave 10 bundle remains intentionally blocked below `qa-proved`
-- Wave 11 is still pending and must not be used to paper over unresolved Wave 10 blockers
-
-### Post-v1 Docx Waves (`wave-12` to `wave-18`)
-
-These remain docx-specific capability waves:
-
-- `wave-12`: tables, projected fidelity, browser-font approximation, initial AI contract
-- `wave-13`: versions, compare, and bounded drafting
-- `wave-14`: legal semantics
-- `wave-15`: structured authoring, permissions, sections, and signatures
-- `wave-16`: document-shell completeness
-- `wave-17`: advanced review and object fidelity
-- `wave-18`: final legal-checklist closure
-
-They should not be read as generic office-suite phases.
-
-## Shared Platform Extraction Plan
-
-The next shared architecture work should focus on what is already reusable in principle:
-
-- package io discipline
-- preservation and reattachment plumbing
-- compatibility taxonomy and reporting vocabulary
-- validator-service boundaries
-- host snapshot and event doctrine
-
-This work should be documented and phased first before claiming a fully neutral source layout.
-
-Canonical docs:
-
-- `docs/architecture/platform/shared-openxml-editor-platform.md`
-- `docs/reference/platform/shared-ooxml-platform-guidance.md`
-
-## Active Xlsx Track
-
-The xlsx track is executing as a sibling runtime, not as an appendage of the docx editor.
-
-Wave 25 (first xlsx wave, 2026-04-03) has landed:
-- `src/formats/xlsx/model/` — canonical workbook model
-- `src/formats/xlsx/io/` — SpreadsheetML parsers
-- `xlsx-canonical-workbook-model` and `xlsx-import-and-normalization` at `baseline-proved`
-
-Canonical architecture docs:
-
-- `docs/architecture/xlsx/spreadsheet-editor-frontend-architecture.md`
-- `docs/architecture/xlsx/canonical-workbook-model-and-commands.md`
-- `docs/reference/xlsx/xlsx-ooxml-compliance.md`
-- `docs/plans/xlsx/xlsx-fixture-corpus-and-certification-plan.md`
-
-Execution rules for xlsx:
-
-- do not copy docx-specific review or ProseMirror assumptions into the spreadsheet runtime
-- reuse shared platform doctrine only where the concern is genuinely format-agnostic
-- require separate fixture, certification, and Excel reopen proof before claiming supported-roundtrip features
-- do not inherit docx wave promotions by implication
-
-## Future Agent Layer
-
-The future agent or LLM interaction layer belongs above format runtimes and below host-facing product flows.
-
-It should:
-
-- request structured context from runtimes
-- propose typed commands rather than mutate state directly
-- respect compatibility blockers
-- stay explicit, reviewable, and auditable
-
-It is a later shared capability, not part of the currently shipped docx API contract.
-
-## Future Pdf Direction
-
-`pdf` is part of the broader repo naming direction, but it remains future exploration only.
-
-For now:
-
-- keep it out of the first shared OOXML platform contract
-- do not imply a shipped pdf editor surface
-- document it as future work rather than present architecture
-
-## Documentation Rules
-
-- Keep repo-level docs broad enough for the office-platform story.
-- Keep shipped docx contracts explicit and docx-specific.
-- Promote xlsx docs into canonical planned locations instead of leaving them as isolated research only.
-- Keep waves and maturity docs honest about which track they describe.
-- Distinguish current source layout from target source layout everywhere it matters.
-
-## Near-Term Execution Order
-
-1. Complete docx shipping roadmap Phases 2–6 (tables, npm publish, validator CI, legal features, hardening).
-   - Wave 20 landed `table-editing` at `baseline-proved`.
-   - Wave 28 landed `editor-feature-parity` at `baseline-proved`: rich formatting marks, image insertion, search plugin, `useDocxEditor` hook, headless CLI.
-   - Wave 29 landed `ooxml-parsing-fidelity` at `baseline-proved`: complete paragraph/run/table property parsing, field codes, bookmarks, section breaks.
-   - Wave 32 landed `ooxml-property-completeness` at `baseline-proved`: widowControl, paragraph borders and shading, bidi, suppressLineNumbers, cnfStyle; charSpacing, kerning, emboss, imprint, shadow, position, textFill run marks; tblLook; ColumnBreakNode, SymbolNode; latent styles.
-   - Wave 33 landed `document-sub-parts` at `baseline-proved`: headers, footers (default/first-page/even-odd variants), footnotes, and endnotes, plus captured and preserved theme metadata from `theme1.xml`; full theme style-resolution and authored theme editing/export remain future work.
-   - Wave 34 landed `structural-block-types` at `baseline-proved`: SDT blocks, custom XML wrappers, altChunk relationship preservation, nested tables, and floating-image anchor metadata with inline editor fallback.
-   - Wave 35 landed `track-change-extensions` at `baseline-proved`: property change revisions (pPrChange, sectPrChange, tblPrChange, rPrChange) and move tracking (moveFrom/moveTo) with linked move IDs; sectPrChange and tblPrChange are actionable; pPrChange is preserve-only with PropertyChangeData metadata.
-   - Wave 36 landed `complex-rendering` at `baseline-proved`: charts, SmartArt, wps shapes, WordArt, and VML rendered as read-only labeled previews; five new canonical inline types (ChartPreviewNode, SmartArtPreviewNode, ShapeNode, WordArtNode, VmlShapeNode) each with rawXml for lossless round-trip; dedicated PM atoms; parse dispatch into parse-main-document.ts is a non-blocking follow-on.
-2. Close xlsx Wave 25 proof gap (A2 missing xlsx-session.ts and import-tests.json).
-3. Continue xlsx track Waves 26–27 (export/serialization, command runtime, grid surface) after Wave 25 closes.
-4. Use the shared platform docs to guide OPC and preservation extraction when xlsx actually needs it.
-5. Revisit future pdf work only after the OOXML sibling story is stable.
-
-Note: Wave 10 "qa-proved certification" and Wave 11 "fleet-ready packaging" are superseded by the Phase 1 and Phase 3 shipping milestones in the current roadmap.