@beyondwork/docx-react-component 1.0.0 → 1.0.2

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

@@ -1,321 +0,0 @@
-# Wave 15 - Structured Authoring, Permissions, And AI Policy Operations
-
-**Commit message**: `Build: add structured authoring and AI policy operations`
-
-## Component promotions
-
-- command-and-transaction-runtime: 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
-
-## Scope note
-
-Wave 15 continues Tier B closure by turning the legal-semantics layer into
-controlled legal authoring through content controls, permissions, protected
-ranges, template linkage, section-level document structure, and signature-block
-semantics.
-
-This wave also makes the lock model explicit: `policy locks` and
-`compatibility-safety locks` are separate concepts, and AI operations must obey
-both.
-
-## Entry criteria
-
-- Wave 14 semantics contracts are stable enough to bind content controls and
-  permissions to clause-aware state.
-- Version and compare flows from Wave 13 remain compatible with protected draft
-  states.
-- The reserved AI action surface is already stable enough to layer
-  policy-aware operations on top of permissions and protected ranges.
-
-## Promotion conditions
-
-- content controls and fields are typed, validated, and export-safe on the
-  owned slice
-- permission and lock behavior blocks disallowed edits predictably
-- section and page-setup structures are no longer preserve-only on the
-  supported signature and exhibit slice
-- signature blocks carry typed roles and export-safe structure
-- policy-aware AI actions respect permissions, protected ranges, suggest-only
-  states, and workflow gates without pretending unsupported regions are editable
-
-## Deliverables
-
-- content-control descriptors, template bindings, and validation state
-- typed permission, protected-range, suggest-only, policy-lock, and
-  compatibility-lock contracts
-- section and page-setup metadata plus signature-role structures
-- policy-aware AI actions for suggestion, edit, resolve, and workflow requests
-- shared docs that keep structured authoring calm, explicit, and policy-driven
-
-## Deploy environments
-
-- staging: railway-cli (shared workspace validation environment)
-
-## Context7 defaults
-
-- bundle: word-editor-contracts
-- query: "structured authoring, content controls, permissions, protected ranges, policy vs compatibility locks, sections, page setup, signature workflow semantics, and policy-aware AI actions"
-
-## Agent A0: cont-QA
-
-### Role prompts
-
-- docs/agents/wave-cont-qa-role.md
-
-### Executor
-
-- profile: deep-review
-
-### Context7
-
-- bundle: word-editor-testing
-- query: "structured-authoring closure, permission and lock proof, bounded policy claims, and policy-aware AI actions"
-
-### Prompt
-
-```text
-Primary goal:
-- Refuse closure unless structured authoring, permissions, and signature workflow semantics are bounded, typed, and machine-visible.
-
-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-15.md.
-
-Specific expectations:
-- block closure if permission and lock behavior still depends on ad hoc UI state
-- block closure if content controls or sections silently fall back to preserve-only behavior on the owned slice
-- block closure if the wave still treats policy locks and compatibility-safety locks as the same thing
-- block closure if AI actions can cross protected ranges or ignore permission gates
-- keep footnotes, headers, footers, and generated-index work clearly deferred
-
-File ownership (only touch these paths):
-- docs/plans/waves/reviews/wave-15-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 content controls, permissions, policy-vs-compatibility locks, sections, signature-block proof, and AI policy behavior into one coherent surface"
-
-### Prompt
-
-```text
-Primary goal:
-- Decide whether the repo now owns a coherent structured-authoring 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-15.md.
-
-Specific expectations:
-- block closure if content-control, permissions, and signature semantics disagree across runtime, export, and docs
-- block closure if section or page-setup ownership remains ambiguous on the supported slice
-- block closure if AI policy actions do not respect permission and protected-range truth
-- keep full document-shell completeness and advanced automation explicitly deferred
-
-File ownership (only touch these paths):
-- .tmp/main-wave-launcher/integration/wave-15.md
-- .tmp/main-wave-launcher/integration/wave-15.json
-```
-
-## Agent A9: Documentation Steward
-
-### Role prompts
-
-- docs/agents/wave-documentation-role.md
-
-### Executor
-
-- profile: docs-pass
-
-### Context7
-
-- bundle: word-editor-contracts
-- query: "documenting structured authoring, permissions, lock taxonomy, signature workflow boundaries, policy-aware AI actions, and the remaining roadmap"
-
-### Prompt
-
-```text
-Primary goal:
-- Close the shared-plan docs around the Wave 15 structured-authoring and policy-aware AI slice without implying broader document-shell or automation 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 15 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: Structured Authoring And Permission Runtime
-
-### Executor
-
-- profile: proof-owner
-- retry-policy: sticky
-
-### Context7
-
-- bundle: word-editor-contracts
-- query: "content controls, permissions, protected ranges, sections, page setup, signature workflow semantics, and lock taxonomy"
-
-### Skills
-
-- role-implementation
-- domain-editor-architecture
-- domain-legal-review
-
-### Components
-
-- command-and-transaction-runtime
-- 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/runtime/structured-authoring-runtime.ts
-- src/ui-tailwind/review/tw-structured-authoring-panel.tsx
-- src/model/permissions.ts
-- test/runtime/structured-authoring.test.ts
-- docs/plans/waves/reviews/wave-15-structured-authoring-proof.md
-
-### Proof artifacts
-
-- path: .tmp/wave-15-structured-authoring/content-controls-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-15-structured-authoring/permissions-and-locks-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-15-structured-authoring/sections-and-page-setup-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-15-structured-authoring/signature-block-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-15-structured-authoring/template-binding-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-15-structured-authoring/word-reopen-notes.md | kind: proof-note | required-for: fleet-ready
-
-### Prompt
-
-```text
-Primary goal:
-- Turn legal semantics into controlled structured authoring with explicit permissions and signature workflow behavior.
-
-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:
-- content controls and permissions must be typed, validated, and export-safe on the owned slice
-- protected ranges should block disallowed edits predictably instead of leaking through soft UI hints
-- policy locks and compatibility-safety locks must remain distinguishable in runtime truth and diagnostics
-- keep macros, OLE, and advanced automation explicitly out of scope
-
-File ownership (only touch these paths):
-- src/runtime/structured-authoring-runtime.ts
-- src/ui-tailwind/review/tw-structured-authoring-panel.tsx
-- src/model/permissions.ts
-- test/runtime/structured-authoring.test.ts
-- docs/plans/waves/reviews/wave-15-structured-authoring-proof.md
-- .tmp/wave-15-structured-authoring/
-```
-
-## Agent A2: Policy-Aware AI Actions And Workflow Gates
-
-### Executor
-
-- profile: implement-fast
-- budget.minutes: 50
-
-### Context7
-
-- bundle: word-editor-contracts
-- query: "policy-aware AI actions, protected ranges, suggest-only workflows, signature-state gating, and permission-respecting legal editor operations"
-
-### 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-policy-operations.ts
-- src/ui-tailwind/review/tw-ai-policy-operations-panel.tsx
-- test/runtime/ai-policy-operations.test.ts
-- docs/plans/waves/reviews/wave-15-ai-policy-proof.md
-
-### Proof artifacts
-
-- path: .tmp/wave-15-structured-authoring/ai-protected-range-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-15-structured-authoring/ai-permission-gate-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-15-structured-authoring/ai-signature-workflow-report.json | kind: integration-report | required-for: fleet-ready
-
-### Prompt
-
-```text
-Primary goal:
-- Add policy-aware AI actions that respect the structured authoring model, protected ranges, and signature/workflow gates.
-
-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:
-- AI actions must be blocked or downgraded when permissions, protected ranges, or workflow state disallow the requested operation
-- distinguish policy denial from compatibility-safety denial in runtime results and UX
-- do not imply document-shell ownership, macro handling, or broad autonomous workflow orchestration in this wave
-
-File ownership (only touch these paths):
-- src/runtime/ai-policy-operations.ts
-- src/ui-tailwind/review/tw-ai-policy-operations-panel.tsx
-- test/runtime/ai-policy-operations.test.ts
-- docs/plans/waves/reviews/wave-15-ai-policy-proof.md
-- .tmp/wave-15-structured-authoring/
-```

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

@@ -1,316 +0,0 @@
-# Wave 16 - Document Shell Completeness And Shell-Aware AI Operations
-
-**Commit message**: `Build: complete the document shell and shell-aware AI operations`
-
-## Component promotions
-
-- docx-import-and-normalization: fleet-ready
-- docx-export-and-serialization: fleet-ready
-- unsupported-ooxml-preservation: fleet-ready
-- compatibility-and-word-validation: fleet-ready
-- react-editor-ui: fleet-ready
-
-- command-and-transaction-runtime: baseline-proved
-## Scope note
-
-Wave 16 opens the document-shell portion of Tier C closure by owning or
-trustworthily projecting the parts of the document shell that legal workflows
-rely on most: headers, footers, notes, pagination cues, and generated indexes.
-
-It is deliberately narrower than final parity closure. The goal here is
-document-shell completeness, not the final integrated all-up proof line.
-
-## Entry criteria
-
-- Waves 12 through 15 are closed or frozen enough that document-shell work can
-  attach to one coherent post-v1 surface without redefining earlier ownership.
-- Shared docs already separate owned document-shell behavior from preserve-only
-  or explicitly deferred behaviors.
-
-## Promotion conditions
-
-- document-shell structures needed for legal workflows are owned on the declared
-  slice rather than preserved passively
-- pagination and generated-index claims remain bounded and test-backed
-- shell-aware AI operations only target surfaces with explicit mapping,
-  validation, and export guarantees
-- remaining Tier C gaps outside the shell stay clearly deferred to Wave 17 or
-  Wave 18
-
-## Deliverables
-
-- header, footer, note, pagination, and generated-index projections or owned
-  surfaces on the declared slice
-- compatibility reporting for document-shell completeness versus preserve-only
-  regions
-- shell-aware AI operations with bounded selection/anchor targeting
-- shared docs that keep shell completeness bounded and distinct from final
-  parity closure
-
-## Deploy environments
-
-- staging: railway-cli (shared workspace validation environment)
-
-## Context7 defaults
-
-- bundle: word-editor-ooxml
-- query: "headers, footers, notes, pagination cues, generated indexes, document-shell completeness, and shell-aware AI operations"
-
-## Agent A0: cont-QA
-
-### Role prompts
-
-- docs/agents/wave-cont-qa-role.md
-
-### Executor
-
-- profile: deep-review
-
-### Context7
-
-- bundle: word-editor-testing
-- query: "document-shell closure, shell-aware AI operations, and bounded pagination claims"
-
-### Prompt
-
-```text
-Primary goal:
-- Refuse closure unless document-shell completeness and shell-aware operations both have current, bounded 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-16.md.
-
-Specific expectations:
-- block closure if document-shell ownership is still mostly preserve-only on the declared slice
-- block closure if pagination or generated-index claims drift past the actual proof
-- block closure if shell-aware AI claims exceed the shell surfaces the repo can map safely
-- keep exact Word layout parity and advanced automation explicitly out of scope
-
-File ownership (only touch these paths):
-- docs/plans/waves/reviews/wave-16-cont-qa.md
-```
-
-## Agent A8: Integration Steward
-
-### Role prompts
-
-- docs/agents/wave-integration-role.md
-
-### Executor
-
-- profile: deep-review
-
-### Context7
-
-- bundle: word-editor-ooxml
-- query: "reconciling document-shell ownership, pagination diagnostics, generated-index proof, and shell-aware AI behavior"
-
-### Prompt
-
-```text
-Primary goal:
-- Decide whether the repo now owns a coherent document-shell slice with bounded shell-aware operations.
-
-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-16.md.
-
-Specific expectations:
-- block closure if document-shell import/export, compatibility, and UI trust surfaces disagree
-- block closure if shell-aware AI operations are not bounded to trustworthy shell mappings
-- keep exact layout parity, advanced automation, and final all-up parity proof explicitly deferred
-
-File ownership (only touch these paths):
-- .tmp/main-wave-launcher/integration/wave-16.md
-- .tmp/main-wave-launcher/integration/wave-16.json
-```
-
-## Agent A9: Documentation Steward
-
-### Role prompts
-
-- docs/agents/wave-documentation-role.md
-
-### Executor
-
-- profile: docs-pass
-
-### Context7
-
-- bundle: word-editor-contracts
-- query: "document-shell completeness, pagination caveats, generated indexes, shell-aware AI operations, and roadmap closure"
-
-### Prompt
-
-```text
-Primary goal:
-- Close the shared-plan docs around the Wave 16 document-shell and shell-aware AI slice without implying exact Word parity or final parity closure.
-
-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 16 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: Document Shell Ownership And Bounded Projection
-
-### Executor
-
-- profile: proof-owner
-- retry-policy: sticky
-
-### Context7
-
-- bundle: word-editor-ooxml
-- query: "document shell import/export, headers, footers, notes, pagination cues, generated indexes, and bounded shell projection"
-
-### Skills
-
-- role-implementation
-- domain-editor-architecture
-- domain-docx-compatibility
-
-### Components
-
-- docx-import-and-normalization
-- docx-export-and-serialization
-- unsupported-ooxml-preservation
-- compatibility-and-word-validation
-- react-editor-ui
-
-### Exit contract
-
-- completion: authoritative
-- durability: durable
-- proof: integration
-- doc-impact: owned
-
-### Deliverables
-
-- src/io/ooxml/parse-document-shell.ts
-- src/io/export/serialize-document-shell.ts
-- src/ui-tailwind/review/tw-document-shell-panel.tsx
-- test/io/document-shell-roundtrip.test.ts
-- docs/plans/waves/reviews/wave-16-platform-proof.md
-
-### Proof artifacts
-
-- path: .tmp/wave-16-legal-platform/document-shell-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-16-legal-platform/headers-footers-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-16-legal-platform/notes-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-16-legal-platform/pagination-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-16-legal-platform/toc-and-index-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-16-legal-platform/document-shell-slice-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-16-legal-platform/word-reopen-notes.md | kind: proof-note | required-for: fleet-ready
-
-### Prompt
-
-```text
-Primary goal:
-- Close the remaining document-shell gap on the declared slice without faking exact Word parity or claiming final all-up closure.
-
-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:
-- own the declared document-shell slice instead of preserving it passively
-- keep pagination and generated-index claims bounded and test-backed
-- keep projected-versus-owned shell behavior explicit in diagnostics and docs
-
-File ownership (only touch these paths):
-- src/io/ooxml/parse-document-shell.ts
-- src/io/export/serialize-document-shell.ts
-- src/ui-tailwind/review/tw-document-shell-panel.tsx
-- test/io/document-shell-roundtrip.test.ts
-- docs/plans/waves/reviews/wave-16-platform-proof.md
-- .tmp/wave-16-legal-platform/
-```
-
-## Agent A2: Shell-Aware AI Operations
-
-### Executor
-
-- profile: implement-fast
-- budget.minutes: 50
-
-### Context7
-
-- bundle: word-editor-ooxml
-- query: "shell-aware AI operations, header/footer editing proposals, note-aware suggestions, pagination-safe targeting, and validate/export confirmation flows"
-
-### Skills
-
-- role-implementation
-- domain-editor-architecture
-- domain-docx-compatibility
-
-### 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-shell-operations.ts
-- src/ui-tailwind/review/tw-ai-shell-operations-panel.tsx
-- test/runtime/ai-shell-operations.test.ts
-- docs/plans/waves/reviews/wave-16-ai-shell-proof.md
-
-### Proof artifacts
-
-- path: .tmp/wave-16-legal-platform/ai-header-footer-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-16-legal-platform/ai-notes-report.json | kind: integration-report | required-for: fleet-ready
-- path: .tmp/wave-16-legal-platform/ai-shell-confirmation-report.json | kind: integration-report | required-for: fleet-ready
-
-### Prompt
-
-```text
-Primary goal:
-- Add shell-aware AI operations only where the runtime can map shell surfaces, validate the result, and preserve export safety.
-
-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/ooxml-compliance.md.
-
-Specific expectations:
-- header/footer/note operations must be bounded to explicitly supported shell targets
-- shell-aware AI results must remain proposal-first and review-confirmed
-- do not imply exact pagination parity, object-level review completeness, or final legal-platform closure in this wave
-
-File ownership (only touch these paths):
-- src/runtime/ai-shell-operations.ts
-- src/ui-tailwind/review/tw-ai-shell-operations-panel.tsx
-- test/runtime/ai-shell-operations.test.ts
-- docs/plans/waves/reviews/wave-16-ai-shell-proof.md
-- .tmp/wave-16-legal-platform/
-```