@beyondwork/docx-react-component 1.0.0

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

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

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