@beyondwork/docx-react-component 1.0.0

package/docs/plans/waves/reviews/wave-10-performance-signoff.md

@@ -0,0 +1,55 @@
+# Wave 10 Performance Budget And Large-Document Signoff
+
+Generated on `2026-03-27T10:10:00Z` for Wave 10 / A6.
+
+Status: `passed`
+
+## Scope
+
+- Owner: A6
+- Proof artifacts:
+  - `.tmp/wave-10-certification/performance-budget.json`
+  - `.tmp/wave-10-certification/large-doc-smoke.json`
+  - `.tmp/wave-10-certification/performance-raw-results.json`
+
+This signoff covers the mounted editor path on the local harness surface. It does not widen Wave 10 support claims.
+
+## Measured Results
+
+### `F10` threaded comments and resolve
+
+- load: `623 ms`
+- comment navigation: `58 ms`
+- export: `117 ms`
+- result: pass
+
+### `S01` SOW template
+
+- load: `656 ms`
+- export: `162 ms`
+- result: pass
+
+### `S02` BW Partner User Licence Agreement with review markup
+
+- load: `3464 ms`
+- single-item accept latency: `771 ms`
+- export after accept: intentionally blocked
+- result: pass under the bounded v1 contract
+
+The current runtime still refuses export after that review action with:
+
+> DOCX export is blocked because 1 preserve-only comment anchors cannot be safely remapped after runtime edits.
+
+That is no longer treated as a performance failure. The current scenario note and Wave 10 contract now judge this as the expected fail-closed outcome for a path that would otherwise destructively rewrite preserve-only anchors.
+
+## Judgement
+
+Wave 10 performance signoff now passes on the current worktree because:
+
+- all measured interactive latencies stay inside the declared Wave 10 ceilings
+- `S02` load and single-item accept stay inside budget
+- the `S02` post-accept export guard is explicit, fast-failing, and consistent with the bounded v1 contract rather than a hidden runtime regression
+
+## Remaining Closure Work
+
+This signoff does not close Wave 10 overall. The remaining blockers are outside A6 scope: pending manual Word notes and the need to rerun the bundle on a commit-fresh tree.

package/docs/plans/waves/reviews/wave-10-regression-proof.md

@@ -0,0 +1,23 @@
+# Wave 10 Regression Proof
+
+status: blocked
+
+## Scope
+
+Wave 10 A1 owns the machine-visible regression gate for the frozen `F01` through `F21` fixture corpus and the representative `S01` and `S02` scenario bundle.
+
+## Current Evidence
+
+- `test/fixtures/docx/certification-manifest.json` keeps `F01` through `F21` as the frozen release-gate corpus, requires `S01` and `S02` as representative scenarios, removes `S02` from the manual Word subset, and marks `S02` as an expected blocked-before-export scenario.
+- Fresh source-run artifacts under `.tmp/wave-10-certification/` now show `F09` and `F13` validator-clean again.
+- `S02` still records `blocked-before-export`, but that outcome is now judged as explicit fail-closed proof rather than as an unresolved export bug.
+- `pnpm --dir services/react-word-editor test` passes on the refreshed worktree.
+
+## Current Blocking Set
+
+- the working tree is still dirty, so the bundle is not commit-fresh
+- required manual Word notes are still pending for `F01`, `F03`, `F05`, `F09`, `F11`, `F12`, `F15`, `F20`, and `S01`
+
+## Conclusion
+
+Wave 10 regression machinery is now aligned to the bounded v1 contract, but the wave still stays blocked until the remaining manual notes are attached and the bundle is rerun on a clean commit.

package/docs/plans/waves/reviews/wave-10-release-audit.md

@@ -0,0 +1,31 @@
+# Wave 10 Release Audit
+
+Generated on `2026-03-27T10:10:00Z` for Wave 10 / A7.
+
+Verdict: `BLOCKED`
+
+[wave-gate] architecture=pass integration=blocked durability=blocked live=blocked docs=pass detail=Wave 10 no longer carries the stale F09/F13 validator failures or the stale S02 exportability claim, but it still needs fresh manual Word notes and a commit-fresh rerun before qa-proved can be claimed honestly.
+
+## Current Findings
+
+1. The machine-backed blocker set is now smaller and current.
+
+- `F09` and `F13` are validator-clean in the stored Wave 10 run artifacts.
+- `S02` remains in the bundle as an explicit fail-closed scenario instead of a required exportable review path.
+- Accessibility, DESIGN, and performance signoff have been refreshed on the current worktree.
+
+2. Wave 10 is still not ready to promote.
+
+- `word-desktop-certification.md` and `word-web-certification.md` remain `pending`.
+- The remaining manual subset is `F01`, `F03`, `F05`, `F09`, `F11`, `F12`, `F15`, `F20`, and `S01`.
+- The current working tree is still dirty, so the existing bundle cannot yet satisfy the commit-fresh closure requirement.
+
+## Smallest Remaining Set
+
+- attach fresh Word Desktop notes for the remaining manual subset
+- attach fresh Word Web notes for the remaining manual subset
+- rerun the Wave 10 bundle on a commit-fresh tree
+
+## Closure Recommendation
+
+Keep Wave 10 blocked until those three items are complete. Do not widen scope into Wave 11 or Wave 12.

package/docs/plans/waves/reviews/wave-10-service-proof.md

@@ -0,0 +1,83 @@
+# Wave 10 Service Proof
+
+## Scope
+
+- Owned components:
+  - `openxml-sdk-validator-service`
+  - `railway-test-harness`
+- Owned deliverables:
+  - [Program.cs](/home/coder/docx-react-component/services/openxml-validator/Program.cs)
+  - [README.md](/home/coder/docx-react-component/services/openxml-validator/README.md)
+  - [README.md](/home/coder/docx-react-component/services/react-word-editor/README.md)
+- Proof artifacts:
+  - [service-health-matrix.json](/home/coder/docx-react-component/.tmp/wave-10-certification/service-health-matrix.json)
+  - [service-proof-summary.md](/home/coder/docx-react-component/.tmp/wave-10-certification/service-proof-summary.md)
+
+This pass hardens the internal QA service contract without changing the product runtime boundary:
+the validator remains validation-only, and the harness remains an internal-only surface that fronts
+the validator over server-side networking.
+
+## Landed Changes
+
+### Validator service
+
+[Program.cs](/home/coder/docx-react-component/services/openxml-validator/Program.cs) now exposes a
+machine-readable readiness payload and structured failure payloads:
+
+- `GET /health` returns `service`, `status`, `sdk`, `privateMode`, `limits`, and `endpoints`
+- `POST /validate` now returns structured JSON for `400`, `413`, and private-mode `503` errors
+- the error contract includes exact upload limits and accepted `.docx` metadata so the harness and
+  QA bundle can surface deterministic diagnostics
+
+[README.md](/home/coder/docx-react-component/services/openxml-validator/README.md) now matches the
+runtime contract and explicitly records the remaining fleet-ready gaps: env-var-only admission,
+request-scoped diagnostics only, and no validator-side audit store or SLO bundle.
+
+### Harness documentation
+
+[README.md](/home/coder/docx-react-component/services/react-word-editor/README.md) now documents the
+actual private-mode gate (`HARNESS_PRIVATE_MODE=enabled`), the redacted health payload shape, the
+volume-backed retention assumptions, and the remaining fleet-ready blockers around identity,
+retention workflow, and single-dependency validator bridging.
+
+## Proof
+
+The authoritative integration proof for this turn is in
+[service-health-matrix.json](/home/coder/docx-react-component/.tmp/wave-10-certification/service-health-matrix.json).
+
+Key observations from the captured matrix:
+
+- validator build passed locally
+- harness build and tests passed locally
+- validator health succeeded with `VALIDATOR_PRIVATE_MODE=enabled`
+- validator rejected a missing multipart file with structured JSON instead of a bare status code
+- validator accepted `F12-redlines-paragraph-joins-splits.docx` with zero package and SDK findings
+- harness returned `503 private_mode_required` when `HARNESS_PRIVATE_MODE` was unset
+- harness health succeeded once private mode and the validator bridge were configured
+- harness `/api/validate` successfully proxied the same `F12` fixture to the validator and
+  returned the validator report plus current storage assumptions
+
+## Validation Commands
+
+- `dotnet build services/openxml-validator/OpenXmlValidator.Api.csproj`
+- `pnpm --filter @docx-react-component/react-word-editor-harness test`
+- `pnpm --filter @docx-react-component/react-word-editor-harness build`
+- `VALIDATOR_PRIVATE_MODE=enabled dotnet run --project services/openxml-validator/OpenXmlValidator.Api.csproj --urls http://127.0.0.1:5081`
+- `PORT=3403 HARNESS_PRIVATE_MODE=enabled OPENXML_VALIDATOR_BASE_URL=http://127.0.0.1:5081 HARNESS_STORAGE_DIR=/home/coder/docx-react-component/.tmp/wave-10-certification/harness-storage pnpm --filter @docx-react-component/react-word-editor-harness start`
+- `curl -s http://127.0.0.1:5081/health`
+- `curl -s -X POST http://127.0.0.1:5081/validate`
+- `curl -s -F "file=@test/fixtures/docx/F12-redlines-paragraph-joins-splits.docx" http://127.0.0.1:5081/validate`
+- `curl -s http://127.0.0.1:3403/api/health`
+- `curl -s -F "file=@test/fixtures/docx/F12-redlines-paragraph-joins-splits.docx" http://127.0.0.1:3403/api/validate`
+
+## Closure Line
+
+Wave 10 service QA hardening is met for local authoritative integration proof and owned
+documentation.
+
+This is not a fleet-ready claim. The remaining service posture gaps are deliberate and documented:
+
+- env-var-only admission for both services
+- manual/count-based storage retention on the harness
+- no persistent validator-side audit or replay surface
+- no fresh Railway live redeploy captured in this turn

package/docs/plans/waves/reviews/wave-10-word-certification.md

@@ -0,0 +1,31 @@
+# Wave 10 Word Certification Review
+
+Generated on `2026-03-27T10:10:00Z` for Wave 10 / A2.
+
+Status: `blocked`
+
+## Current Manual Word Subset
+
+Wave 10 still requires fresh Word Desktop and Word Web notes for:
+
+- `F01`
+- `F03`
+- `F05`
+- `F09`
+- `F11`
+- `F12`
+- `F15`
+- `F20`
+- `S01`
+
+`S02` remains visible in the bundle, but it is no longer part of the manual reopen subset because the bounded v1 contract intentionally blocks export when preserve-only comment anchors cannot be remapped safely.
+
+## Current Evidence
+
+- `F09` is now validator-clean again and remains in the manual subset as supported-roundtrip Word proof, not as a validator blocker.
+- `S01` remains the only representative scenario that still requires Word reopen notes.
+- `word-desktop-certification.md` and `word-web-certification.md` now point at the reduced manual subset and no longer carry the stale `F09` validator-failure language.
+
+## Remaining Blocker
+
+Wave 10 still lacks fresh human Word Desktop and Word Web observations for the remaining manual subset. Until those notes exist, the wave cannot honestly claim `qa-proved`.

package/docs/plans/waves/reviews/wave-18-ai-contract-closure.md

@@ -0,0 +1,277 @@
+# Wave 18 AI Contract Closure
+
+## Executive Summary
+
+Wave 18 establishes the comprehensive AI action policy matrix and low-priority Word surfaces stance for the legal document review editor. This document provides the definitive boundaries between allowed AI actions, those requiring confirmation, blocked operations, and unsupported functionality.
+
+**Key Achievements:**
+- ✅ Complete AI action policy matrix with 23 defined actions across 10 categories
+- ✅ Explicit low-priority Word surfaces stance for 12 surface types
+- ✅ Security-focused boundaries that protect legal review workflows
+- ✅ Clear preserve-only vs. blocked distinctions for complex Word features
+
+## AI Action Policy Matrix
+
+### Policy Framework
+
+The AI action policy is built on four support levels:
+- **Allowed**: Actions can proceed without confirmation (low risk, analytical)
+- **Confirmation Required**: Actions require explicit user approval (content-changing)
+- **Blocked**: Actions are blocked by policy (security/integrity risks)
+- **Unsupported**: Actions are not implemented (future consideration)
+
+### Action Categories and Support Levels
+
+| Category | Total Actions | Allowed | Confirmation Required | Blocked | Risk Profile |
+|----------|---------------|---------|----------------------|---------|--------------|
+| Text Editing | 5 | 1 | 4 | 0 | Low-Medium |
+| Content Generation | 5 | 1 | 4 | 0 | Low-High |
+| Review Assistance | 5 | 5 | 0 | 0 | Low |
+| Document Analysis | 5 | 5 | 0 | 0 | Low |
+| Formatting Assistance | 5 | 0 | 5 | 0 | Medium |
+| Validation Assistance | 5 | 5 | 0 | 0 | Low |
+| Workflow Automation | 5 | 0 | 1 | 4 | High-Critical |
+| Data Extraction | 5 | 5 | 0 | 0 | Low |
+| External Integration | 5 | 0 | 0 | 5 | Critical |
+| System Modification | 5 | 0 | 0 | 5 | Critical |
+
+### Security Boundaries
+
+**Completely Blocked Actions** (10 actions):
+- All workflow automation that bypasses review (auto-accept changes)
+- All external integrations (data lookup, system sync, external approval)
+- All system modifications (permission changes, security bypasses)
+
+**Rationale**: These actions either compromise security, bypass necessary legal review processes, or risk data integrity in ways incompatible with legal document workflows.
+
+### Allowed Actions (Analysis and Read-Only)
+
+**Low-Risk Allowed Actions** (16 actions):
+- Document analysis (summarization, risk identification, structure analysis)
+- Review assistance (comment suggestions, change analysis)
+- Validation assistance (compliance checking, compatibility validation)
+- Data extraction (metadata extraction, comment exports)
+- Basic text corrections (grammar fixes with minimal semantic impact)
+
+**Key Principle**: Actions that provide analytical insights or mechanical corrections without modifying legal meaning or bypassing review processes.
+
+### Confirmation-Required Actions (Content Changes)
+
+**Content-Modifying Actions** (14 actions):
+- Text editing with semantic impact (rewrites, tone adjustments)
+- Content generation (text generation, boilerplate creation)
+- Formatting changes (style application, bulk formatting)
+- Selective workflow automation (batch comment resolution with review)
+
+**Safeguards**:
+- Explicit user confirmation required
+- Original content preservation
+- Undo support mandatory
+- Audit logging required
+- Compatibility validation enforced
+
+## Low-Priority Word Surfaces Policy
+
+### Surface Classification Matrix
+
+| Surface Type | Stance | Rationale | Fixture Evidence | Word Compatible |
+|--------------|---------|-----------|------------------|-----------------|
+| **Security-Blocked Surfaces** | | | | |
+| Macros | Blocked | Security risk, executable code | None | No |
+| VBA Scripts | Blocked | Security risk, executable code | None | No |
+| ActiveX Controls | Blocked | Deprecated, security risk | None | No |
+| External Data Connections | Blocked | Security, dependency risk | None | No |
+| **Preserve-Only Surfaces** | | | | |
+| OLE Objects | Preserve-Only | Complex binary, compatibility focus | F20 | Yes |
+| Embedded Objects | Preserve-Only | Format-specific, out of scope | F20 | Yes |
+| Mail Merge Fields | Preserve-Only | Static preservation adequate | F17 | Yes |
+| Legacy Form Fields | Preserve-Only | SDTs preferred, compatibility | F18 | Yes |
+| Custom Ribbons | Preserve-Only | UI customization, not content | F20 | Yes |
+| Word Add-ins | Preserve-Only | Application-level, not document | F20 | Yes |
+| External Links | Preserve-Only | Security boundary, preserve only | F20 | Yes |
+| **Unsupported-Fatal Surfaces** | | | | |
+| Advanced Word Automation | Unsupported-Fatal | Complex, use Word directly | None | No |
+
+### Preserve-Only Implementation
+
+**Technical Approach**:
+- Import: Content preserved in package-backed opaque placeholders
+- Edit: Locked regions prevent accidental modification
+- Export: Original content reattached during serialization
+- Warning: Users informed about preservation limitations
+
+**Word Compatibility**: All preserve-only surfaces maintain round-trip safety with Microsoft Word, ensuring no data loss and no repair prompts on reopen.
+
+### Security Boundaries
+
+**Blocked for Security**:
+- **Executable Content**: Macros, VBA scripts, ActiveX controls
+- **External Dependencies**: Data connections, external system integrations
+- **Rationale**: Legal document workflows require contained, auditable content without external dependencies or executable code that could compromise security or introduce non-deterministic behavior.
+
+**Preserve-Only for Compatibility**:
+- **Complex Binary Content**: OLE objects, embedded media
+- **Application Features**: Custom ribbons, add-in definitions
+- **Rationale**: These features can be safely preserved without editing to maintain Word compatibility while keeping the editor focused on core text and review workflows.
+
+## AI Action Validation Framework
+
+### Context-Aware Validation
+
+The AI action policy includes context validation that considers:
+
+```typescript
+interface AIActionContext {
+  documentId: string;
+  userId: string;
+  selection?: { from: number; to: number; text: string };
+  preservedContent: {
+    hasPreservedElements: boolean;
+    preservedTypes: string[];
+  };
+  compatibility: {
+    hasWarnings: boolean;
+    blockingIssues: string[];
+  };
+  permissions: {
+    canEdit: boolean;
+    canExport: boolean;
+    isReadOnly: boolean;
+  };
+}
+```
+
+### Validation Rules
+
+1. **Permission Checks**: Content-modifying actions require edit permissions
+2. **Compatibility Constraints**: Actions requiring validation cannot proceed with blocking compatibility issues
+3. **Preserved Content Respect**: Actions must respect preserve-only boundaries
+4. **Scope Limitations**: Actions are limited to appropriate document scopes (selection, paragraph, document)
+
+### Error Handling
+
+- **Blocked Actions**: Clear error messages with policy rationale
+- **Permission Failures**: Explicit permission requirement notifications
+- **Context Constraints**: Specific guidance on resolving context issues
+- **Graceful Degradation**: Fallback behaviors that maintain editor stability
+
+## Integration with Legal Review Workflow
+
+### Review-Centric Design
+
+**Core Principle**: AI actions support legal review workflows without replacing human judgment or bypassing necessary review processes.
+
+**Supported Workflows**:
+- Document analysis and risk identification
+- Comment response suggestions and thread analysis
+- Change impact assessment and validation
+- Compliance checking and compatibility verification
+- Formatting consistency and style validation
+
+**Blocked Workflows**:
+- Automatic acceptance of changes without review
+- Content generation without explicit user confirmation
+- External data integration that could compromise security
+- System modifications that bypass established controls
+
+### Audit and Compliance
+
+**Audit Logging**:
+- All AI actions logged with user, action, timestamp, and outcome
+- Blocked actions logged for security monitoring
+- Content changes tracked through normal revision system
+- Context validation failures recorded for analysis
+
+**Compliance Support**:
+- AI actions align with legal document integrity requirements
+- No bypass of established Word compatibility validation
+- Preserve-only content boundaries respected by all AI operations
+- User confirmation required for all content-changing proposals
+
+## Implementation Architecture
+
+### Policy Enforcement
+
+**Runtime Validation**:
+- `validateAIAction(action, context)` provides comprehensive validation
+- Policy lookup with fallback to secure defaults for unknown actions
+- Context-aware constraint checking with detailed error reporting
+- Graceful degradation with user-facing guidance
+
+**Security-First Design**:
+- Unknown actions blocked by default
+- Critical risk actions always blocked regardless of context
+- No bypass mechanisms for security-sensitive operations
+- Audit logging for all policy decisions
+
+### Integration Points
+
+**Document Model Integration**:
+- AI actions respect canonical document model boundaries
+- Preserve-only regions remain protected from AI modifications
+- Change tracking and comment systems work normally with AI-generated content
+- Export validation applies to AI-modified content
+
+**User Interface Integration**:
+- Confirmation dialogs for content-changing actions
+- Clear warnings for actions affecting preserved content
+- Progress indication for long-running analysis actions
+- Undo support for all reversible AI actions
+
+## Future Extension Points
+
+### Planned Enhancements
+
+**Post-V1 Considerations**:
+- Additional analysis actions as legal workflows evolve
+- Enhanced content generation with legal-specific templates
+- Integration with legal knowledge bases (with appropriate security controls)
+- Advanced validation against regulatory requirements
+
+**Extension Principles**:
+- Maintain security-first approach for all new actions
+- Require explicit policy definition for new action categories
+- Preserve Word compatibility as primary constraint
+- Keep legal review human judgment as ultimate authority
+
+### API Evolution
+
+**Planned API Shape** (reserved for future waves):
+
+```typescript
+interface PlannedWordReviewEditorAiAdapter {
+  runAction(request: PlannedWordReviewEditorAiRequest): Promise<{
+    kind: "proposal" | "workflow" | "rejected";
+    summary?: string;
+    requiresConfirmation?: boolean;
+    reason?: string;
+  }>;
+}
+```
+
+**Key Constraints** (preserved in future API):
+- No built-in model client in WordReviewEditor
+- No direct DOM or canonical state mutation from AI
+- No bypass of permissions, compatibility, or export validation
+- No implication that unsupported features become editable through AI
+
+## Conclusion
+
+Wave 18 establishes a comprehensive and security-focused framework for AI integration in the legal document review editor. The policy matrix provides clear boundaries that:
+
+1. **Enable Valuable AI Assistance**: Analysis, validation, and review support actions
+2. **Require Appropriate Confirmation**: Content-changing actions with user oversight
+3. **Block Security Risks**: External integrations, system modifications, and executable content
+4. **Preserve Legal Workflow Integrity**: No bypass of review processes or compatibility requirements
+
+The low-priority Word surfaces policy complements this by providing explicit stances on complex Word features, ensuring users understand what can be edited, what is preserved, and what is blocked for security reasons.
+
+This framework provides a solid foundation for AI-assisted legal document workflows while maintaining the security, integrity, and Word compatibility that are essential for legal review processes.
+
+---
+
+**Implementation Status**: ✅ **Complete**
+- Source code implemented in `src/runtime/ai-action-policy.ts` and `src/validation/low-priority-word-surfaces.ts`
+- Comprehensive test coverage in `test/validation/low-priority-word-surfaces.test.ts`
+- Machine-readable policy artifacts generated for integration validation
+- Documentation provides clear guidance for future AI feature development