@beyondwork/docx-react-component 1.0.0 → 1.0.2

package/docs/plans/waves/completed/wave-13.md

@@ -1,316 +0,0 @@
-# Wave 13 - Versions, Compare, And Bounded AI Drafting
-
-**Commit message**: `Build: add versioned compare and bounded AI drafting`
-
-## Component promotions
-
-- canonical-document-model: fleet-ready
-- command-and-transaction-runtime: fleet-ready
-- docx-import-and-normalization: fleet-ready
-- docx-export-and-serialization: fleet-ready
-- react-editor-ui: fleet-ready
-
-## Scope note
-
-Wave 13 closes the remaining Tier A legal-checklist gap after tables by making
-versions, snapshots, and compare first-class product behavior instead of a
-side-effect of harness storage.
-
-It is also the first wave that uses the reserved AI contract for bounded
-drafting operations, but only where durable version lineage and compare context
-make those proposals auditable.
-
-## Entry criteria
-
-- Wave 12 table ownership is closed or frozen enough that compare can operate on
-  the new canonical shapes.
-- Snapshot and export IDs are durable and trustworthy enough to serve as
-  compare anchors.
-- The Wave 12 AI action contract is frozen enough that later drafting
-  operations can build on it without redefining the base integration model.
-
-## Promotion conditions
-
-- hosts can create, name, resume, and compare durable document versions
-- compare output is linked to stable version IDs rather than transient runtime
-  state
-- pre-signature locking or snapshotting is explicit and testable
-- compare evidence is machine-visible, not only UI screenshots
-- bounded AI drafting operations use version/compare context, emit reviewable
-  proposals, and never bypass confirmation or export safety
-
-## Deliverables
-
-- typed version metadata and lineage identifiers
-- compare request and result contracts
-- host-visible compare surfaces backed by durable snapshot references
-- bounded AI drafting workflows backed by versions and compare artifacts
-- shared docs that keep compare bounded and explicit
-
-## Deploy environments
-
-- staging: railway-cli (shared workspace validation environment)
-
-## Context7 defaults
-
-- bundle: word-editor-contracts
-- query: "version lineage, saved snapshots, compare any two versions, compare-backed drafting proposals, and host-visible contracts for a Word-compatible editor"
-
-## Agent A0: cont-QA
-
-### Role prompts
-
-- docs/agents/wave-cont-qa-role.md
-
-### Executor
-
-- profile: deep-review
-
-### Context7
-
-- bundle: word-editor-testing
-- query: "version-lineage closure, compare proof, bounded compare claims, and bounded AI drafting operations"
-
-### Prompt
-
-```text
-Primary goal:
-- Refuse closure unless version lineage, snapshot safety, and compare all have current, machine-visible proof.
-
-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/waves/wave-13.md.
-
-Specific expectations:
-- block closure if compare depends on transient runtime state instead of durable version references
-- block closure if pre-signature or locked-draft behavior is ambiguous
-- block closure if AI drafting proposals are not anchored to saved versions or compare artifacts
-- keep compare bounded to the owned surface; do not imply real-time collaboration, merge resolution, or autonomous drafting
-
-File ownership (only touch these paths):
-- docs/plans/waves/reviews/wave-13-cont-qa.md
-```
-
-## Agent A8: Integration Steward
-
-### Role prompts
-
-- docs/agents/wave-integration-role.md
-
-### Executor
-
-- profile: deep-review
-
-### Context7
-
-- bundle: word-editor-contracts
-- query: "reconciling version lineage, compare contracts, snapshot persistence, host integration proof, and compare-backed AI drafting behavior"
-
-### Prompt
-
-```text
-Primary goal:
-- Decide whether versions, snapshots, and compare now form one coherent product surface.
-
-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/waves/wave-13.md.
-
-Specific expectations:
-- block closure if version lineage, compare UI, and saved artifacts disagree
-- block closure if the repo still treats compare as a harness-only affordance
-- block closure if AI drafting behavior cannot be explained as proposal-first and compare-backed
-- keep the Wave 13 slice bounded and separate from later semantics, permissions, or merge-style collaboration work
-
-File ownership (only touch these paths):
-- .tmp/main-wave-launcher/integration/wave-13.md
-- .tmp/main-wave-launcher/integration/wave-13.json
-```
-
-## Agent A9: Documentation Steward
-
-### Role prompts
-
-- docs/agents/wave-documentation-role.md
-
-### Executor
-
-- profile: docs-pass
-
-### Context7
-
-- bundle: word-editor-contracts
-- query: "documenting version lineage, compare contracts, snapshot safety, bounded AI drafting, and post-v1 roadmap boundaries"
-
-### Prompt
-
-```text
-Primary goal:
-- Close the shared-plan docs around the Wave 13 version, compare, and bounded AI drafting slice without implying wider collaboration or legal semantics ownership.
-
-Required context before coding:
-- Read docs/reference/repository-guidance.md.
-- Read docs/research/agent-context-sources.md.
-- Read docs/reference/legal-checklist.md.
-- Read docs/plans/master-plan.md, docs/plans/current-state.md, docs/plans/migration.md, and docs/plans/component-cutover-matrix.md.
-- Read the Wave 13 proof notes.
-
-File ownership (only touch these paths):
-- README.md
-- docs/roadmap.md
-- docs/plans/master-plan.md
-- docs/plans/current-state.md
-- docs/plans/migration.md
-- docs/plans/component-cutover-matrix.md
-- docs/plans/component-cutover-matrix.json
-- docs/reference/legal-checklist.md
-```
-
-## Agent A1: Version Lineage, Compare, And Audit Surface
-
-### Executor
-
-- profile: proof-owner
-- retry-policy: sticky
-
-### Context7
-
-- bundle: word-editor-contracts
-- query: "version lineage, compare request and result contracts, durable snapshot references, and proposal-safe drafting context"
-
-### Skills
-
-- role-implementation
-- domain-editor-architecture
-- domain-legal-review
-
-### Components
-
-- canonical-document-model
-- command-and-transaction-runtime
-- docx-import-and-normalization
-- docx-export-and-serialization
-- react-editor-ui
-
-### Exit contract
-
-- completion: authoritative
-- durability: durable
-- proof: integration
-- doc-impact: owned
-
-### Deliverables
-
-- src/model/version-lineage.ts
-- src/api/version-compare.ts
-- services/react-word-editor/lib/version-history.ts
-- src/ui-tailwind/review/tw-version-compare-panel.tsx
-- docs/plans/waves/reviews/wave-13-version-proof.md
-
-### Proof artifacts
-
-- path: .tmp/wave-13-versions/version-lineage-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-13-versions/compare-any-two-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-13-versions/pre-signature-snapshot-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-13-versions/audit-trail-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-13-versions/ui-compare-smoke.json | kind: integration-report | required-for: fleet-ready
-
-### Prompt
-
-```text
-Primary goal:
-- Make versions, snapshots, and compare first-class product behavior instead of a side-effect of harness storage.
-
-Required context before coding:
-- Read docs/reference/repository-guidance.md.
-- Read docs/research/agent-context-sources.md.
-- Read docs/reference/public-api.md.
-- Read services/react-word-editor/README.md.
-
-Specific expectations:
-- durable version IDs must anchor compare instead of transient in-memory state
-- compare must stay bounded to one document lineage; do not imply multi-user merge resolution
-- snapshot and export references should be host-visible and auditable
-- AI drafting proposals in this wave must attach to durable versions and compare context, not raw ephemeral editor state
-
-File ownership (only touch these paths):
-- src/model/version-lineage.ts
-- src/api/version-compare.ts
-- services/react-word-editor/lib/version-history.ts
-- src/ui-tailwind/review/tw-version-compare-panel.tsx
-- docs/plans/waves/reviews/wave-13-version-proof.md
-- .tmp/wave-13-versions/
-```
-
-## Agent A2: Compare-Backed AI Drafting Operations
-
-### Executor
-
-- profile: implement-fast
-- budget.minutes: 50
-
-### Context7
-
-- bundle: word-editor-contracts
-- query: "bounded AI drafting operations, compare-backed edit suggestions, version-scoped section rewrites, and review confirmation flows"
-
-### Skills
-
-- role-implementation
-- domain-editor-architecture
-- domain-legal-review
-
-### Components
-
-- command-and-transaction-runtime
-- docx-export-and-serialization
-- react-editor-ui
-
-### Exit contract
-
-- completion: authoritative
-- durability: durable
-- proof: integration
-- doc-impact: owned
-
-### Deliverables
-
-- src/runtime/ai-drafting-operations.ts
-- src/ui-tailwind/review/tw-ai-drafting-panel.tsx
-- test/runtime/ai-drafting-operations.test.ts
-- docs/plans/waves/reviews/wave-13-ai-drafting-proof.md
-
-### Proof artifacts
-
-- path: .tmp/wave-13-versions/ai-section-rewrite-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-13-versions/ai-compare-suggestion-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-13-versions/ai-review-confirmation-report.json | kind: integration-report | required-for: fleet-ready
-
-### Prompt
-
-```text
-Primary goal:
-- Add bounded AI drafting workflows that use durable versions and compare state to produce reviewable legal-draft proposals.
-
-Required context before coding:
-- Read docs/reference/repository-guidance.md.
-- Read docs/research/agent-context-sources.md.
-- Read docs/reference/public-api.md.
-- Read docs/plans/waves/wave-12.md.
-
-Specific expectations:
-- section rewrites and drafting suggestions must bind to saved versions or compare artifacts
-- results must stay proposal-first and require explicit confirmation before canonical application
-- do not imply autonomous clause negotiation, merge resolution, or freeform whole-document rewriting
-
-File ownership (only touch these paths):
-- src/runtime/ai-drafting-operations.ts
-- src/ui-tailwind/review/tw-ai-drafting-panel.tsx
-- test/runtime/ai-drafting-operations.test.ts
-- docs/plans/waves/reviews/wave-13-ai-drafting-proof.md
-- .tmp/wave-13-versions/
-```

package/docs/plans/waves/completed/wave-14.md

@@ -1,319 +0,0 @@
-# Wave 14 - Legal Semantics Core And AI Review Operations
-
-**Commit message**: `Build: add legal semantics and AI review operations`
-
-## Component promotions
-
-- canonical-document-model: fleet-ready
-- docx-import-and-normalization: fleet-ready
-- docx-export-and-serialization: fleet-ready
-- compatibility-and-word-validation: fleet-ready
-- react-editor-ui: fleet-ready
-
-- command-and-transaction-runtime: baseline-proved
-## Scope note
-
-Wave 14 starts Tier B legal-checklist closure. Its job is to turn structurally
-valid documents into meaning-aware legal documents by adding stable clause
-identity, structural references, defined-term modeling, styles governance, and
-legal metadata.
-
-It also makes those typed semantics usable by review workflows, including
-bounded AI review operations that must attach to clauses, references, terms, or
-metadata rather than raw prompt text alone.
-
-## Entry criteria
-
-- Wave 13 version lineage exists so semantic state can be audited across drafts.
-- Numbering and heading behaviors from bounded v1 remain stable enough to carry
-  clause identity without redefining the current text slice.
-- The Wave 13 version and AI drafting surfaces are stable enough that semantics
-  can become the authoritative targeting layer for later drafting/review work.
-
-## Promotion conditions
-
-- clauses have stable identity independent of rendered numbering
-- references survive renumbering or fail loudly with machine-visible diagnostics
-- defined terms and usages are linkable and inspectable
-- styles and document metadata are typed and policy-aware
-- semantics-aware AI review operations stay anchored to typed legal objects and
-  produce reviewable outputs rather than freeform document mutation
-
-## Deliverables
-
-- typed clause, anchor, reference, definition, style-policy, and metadata
-  contracts
-- diagnostics for broken references and term integrity
-- semantics-aware review operations for explanation, term checking, and
-  reference-aware drafting suggestions
-- shared docs that keep semantics separate from rendering or operator-only
-  metadata
-
-## Deploy environments
-
-- staging: railway-cli (shared workspace validation environment)
-
-## Context7 defaults
-
-- bundle: word-editor-contracts
-- query: "clause identity, references, defined terms, styles governance, legal metadata, and semantics-aware AI review for Word-compatible legal documents"
-
-## Agent A0: cont-QA
-
-### Role prompts
-
-- docs/agents/wave-cont-qa-role.md
-
-### Executor
-
-- profile: deep-review
-
-### Context7
-
-- bundle: word-editor-testing
-- query: "semantics closure, reference integrity proof, bounded legal-semantics claims, and semantics-aware AI review operations"
-
-### Prompt
-
-```text
-Primary goal:
-- Refuse closure unless legal semantics are machine-visible, bounded, and consistent across import, edit, export, and diagnostics.
-
-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/waves/wave-14.md.
-
-Specific expectations:
-- block closure if clause identity depends on rendered numbering only
-- block closure if references or defined terms remain narrative instead of typed and testable
-- block closure if AI review operations are not grounded in typed clause/reference/term objects
-- keep permissions, content controls, and section ownership explicitly out of scope
-
-File ownership (only touch these paths):
-- docs/plans/waves/reviews/wave-14-cont-qa.md
-```
-
-## Agent A8: Integration Steward
-
-### Role prompts
-
-- docs/agents/wave-integration-role.md
-
-### Executor
-
-- profile: deep-review
-
-### Context7
-
-- bundle: word-editor-contracts
-- query: "reconciling clause identity, reference integrity, metadata roundtrip, semantics-facing UI proof, and AI review behavior"
-
-### Prompt
-
-```text
-Primary goal:
-- Decide whether the repo now owns a coherent legal-semantics slice.
-
-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/waves/wave-14.md.
-
-Specific expectations:
-- block closure if semantics contracts, diagnostics, and UI trust surfaces disagree
-- block closure if metadata or styles governance stays implicit
-- block closure if AI review claims exceed the typed semantic objects the repo actually owns
-- keep document-shell and permissions work clearly deferred to later waves
-
-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: word-editor-contracts
-- query: "documenting clause identity, references, defined terms, styles policy, metadata, semantics-aware AI review, and the remaining roadmap boundary"
-
-### Prompt
-
-```text
-Primary goal:
-- Close the shared-plan docs around the Wave 14 legal-semantics and semantics-aware AI review slice without implying permissions, content controls, or document-shell ownership.
-
-Required context before coding:
-- Read docs/reference/repository-guidance.md.
-- Read docs/research/agent-context-sources.md.
-- Read docs/reference/legal-checklist.md.
-- Read docs/plans/master-plan.md, docs/plans/current-state.md, docs/plans/migration.md, and docs/plans/component-cutover-matrix.md.
-- Read the Wave 14 proof notes.
-
-File ownership (only touch these paths):
-- README.md
-- docs/roadmap.md
-- docs/plans/master-plan.md
-- docs/plans/current-state.md
-- docs/plans/migration.md
-- docs/plans/component-cutover-matrix.md
-- docs/plans/component-cutover-matrix.json
-- docs/reference/legal-checklist.md
-```
-
-## Agent A1: Clause Identity And Reference Semantics
-
-### Executor
-
-- profile: proof-owner
-- retry-policy: sticky
-
-### Context7
-
-- bundle: word-editor-contracts
-- query: "stable clause identity, structural anchors, references, defined terms, styles governance, legal metadata, and typed semantic targeting"
-
-### Skills
-
-- role-implementation
-- domain-editor-architecture
-- domain-legal-review
-
-### Components
-
-- canonical-document-model
-- docx-import-and-normalization
-- docx-export-and-serialization
-- compatibility-and-word-validation
-- react-editor-ui
-
-### Exit contract
-
-- completion: authoritative
-- durability: durable
-- proof: integration
-- doc-impact: owned
-
-### Deliverables
-
-- src/model/legal-semantics.ts
-- src/runtime/legal-semantics-runtime.ts
-- src/ui-tailwind/review/tw-legal-semantics-panel.tsx
-- test/model/legal-semantics.test.ts
-- docs/plans/waves/reviews/wave-14-semantics-proof.md
-
-### Proof artifacts
-
-- path: .tmp/wave-14-semantics/clause-identity-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-14-semantics/reference-integrity-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-14-semantics/defined-terms-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-14-semantics/styles-policy-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-14-semantics/metadata-roundtrip-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-14-semantics/word-reopen-notes.md | kind: proof-note | required-for: fleet-ready
-
-### Prompt
-
-```text
-Primary goal:
-- Turn structurally valid documents into meaning-aware legal documents without collapsing semantics into presentation-only cues.
-
-Required context before coding:
-- Read docs/reference/repository-guidance.md.
-- Read docs/research/agent-context-sources.md.
-- Read docs/reference/ooxml-compliance.md.
-- Read docs/reference/legal-checklist.md.
-
-Specific expectations:
-- stable clause identity must survive renumbering
-- broken references and defined-term gaps need diagnostics, not silent drift
-- styles and metadata governance must stay typed and export-safe
-- semantic targets used by later AI workflows must resolve to typed objects, not ad hoc text spans
-
-File ownership (only touch these paths):
-- src/model/legal-semantics.ts
-- src/runtime/legal-semantics-runtime.ts
-- src/ui-tailwind/review/tw-legal-semantics-panel.tsx
-- test/model/legal-semantics.test.ts
-- docs/plans/waves/reviews/wave-14-semantics-proof.md
-- .tmp/wave-14-semantics/
-```
-
-## Agent A2: Semantics-Aware AI Review Operations
-
-### Executor
-
-- profile: implement-fast
-- budget.minutes: 50
-
-### Context7
-
-- bundle: word-editor-contracts
-- query: "semantics-aware AI review, clause explanation, defined-term consistency checks, reference-aware drafting suggestions, and review confirmation flows"
-
-### Skills
-
-- role-implementation
-- domain-editor-architecture
-- domain-legal-review
-
-### Components
-
-- command-and-transaction-runtime
-- compatibility-and-word-validation
-- react-editor-ui
-
-### Exit contract
-
-- completion: authoritative
-- durability: durable
-- proof: integration
-- doc-impact: owned
-
-### Deliverables
-
-- src/runtime/ai-semantic-review.ts
-- src/ui-tailwind/review/tw-ai-semantic-review-panel.tsx
-- test/runtime/ai-semantic-review.test.ts
-- docs/plans/waves/reviews/wave-14-ai-review-proof.md
-
-### Proof artifacts
-
-- path: .tmp/wave-14-semantics/ai-clause-explanation-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-14-semantics/ai-defined-term-check-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-14-semantics/ai-reference-aware-suggestion-report.json | kind: integration-report | required-for: fleet-ready
-
-### Prompt
-
-```text
-Primary goal:
-- Add semantics-aware AI review operations that rely on typed clause, reference, term, and metadata objects instead of raw-text guessing.
-
-Required context before coding:
-- Read docs/reference/repository-guidance.md.
-- Read docs/research/agent-context-sources.md.
-- Read docs/reference/public-api.md.
-- Read docs/reference/legal-checklist.md.
-
-Specific expectations:
-- clause explanations, defined-term checks, and reference-aware suggestions must resolve against canonical semantic ids
-- outputs must stay reviewable and must not bypass runtime validation or export safety
-- do not imply policy-aware permissions behavior or document-shell ownership in this wave
-
-File ownership (only touch these paths):
-- src/runtime/ai-semantic-review.ts
-- src/ui-tailwind/review/tw-ai-semantic-review-panel.tsx
-- test/runtime/ai-semantic-review.test.ts
-- docs/plans/waves/reviews/wave-14-ai-review-proof.md
-- .tmp/wave-14-semantics/
-```