@beyondwork/docx-react-component 1.0.0

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

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

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