@beyondwork/docx-react-component 1.0.0

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

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

@@ -0,0 +1,319 @@
+# 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/
+```