@beyondwork/docx-react-component 1.0.0

package/docs/reference/legal-checklist.md

@@ -0,0 +1,445 @@
+Legal DOCX review checklist
+Purpose
+Use this checklist to evaluate whether a React-based legal Word review component is credible for legal review, editing, interoperability, and DOCX round-trip.
+
+Fidelity layers
+Layer 0 — Visual only: looks right, but the system does not deeply understand or safely edit it.
+Layer 1 — Editable presentation: editable and visually preserved, but behavior is mostly generic rich text editing.
+Layer 2 — Structured editing: represented in the document schema with stable identity, predictable editing rules, and import/export mapping.
+Layer 3 — Review-aware semantics: supports comments, redlines, accept/reject, anchoring, filtering, permissions, and compare workflows in a way that matches legal review.
+Layer 4 — Legal-grade semantics: understood as a meaningful legal object, with validations, linkage, navigation, and risk-aware workflows.
+Layer 5 — Round-trip parity: survives DOCX import/export, compare, collaboration, and version history with minimal or no meaningful loss.
+
+Priority matrix
+Element
+Why it matters in legal review
+Recommended target fidelity
+Checklist
+Track changes / redlines
+Core review surface
+Layer 5
+[ ]
+Comments and comment threads
+Negotiation and decisions live here
+Layer 5
+[ ]
+Paragraphs and character runs
+Base unit of text and styling
+Layer 5
+[ ]
+Headings and numbered clauses
+Structure and citation backbone
+Layer 5
+[ ]
+Tables
+Schedules, pricing, SLAs, annexes, disclosure content
+Layer 5
+[ ]
+Lists and nested numbering
+Legal meaning often depends on list structure
+Layer 5
+[ ]
+Cross-references
+Broken references destroy trust
+Layer 4–5
+[ ]
+Defined terms
+High-value legal semantic object
+Layer 4
+[ ]
+Bookmarks / anchors
+Needed for navigation and stable linking
+Layer 4
+[ ]
+Sections / page setup
+Often important in export, signatures, exhibits
+Layer 4
+[ ]
+Footnotes / endnotes
+Used in some legal and regulatory drafting
+Layer 4
+[ ]
+Headers / footers
+Matter for drafts, confidentiality, version labeling
+Layer 3–4
+[ ]
+Images / shapes / text boxes
+Usually secondary, but sometimes matter in exhibits
+Layer 2–3
+[ ]
+Fields / content controls
+Useful for templates and structured generation
+Layer 4
+[ ]
+Metadata / document properties
+Workflow context and status
+Layer 4
+[ ]
+Permissions / locks
+Required for controlled review
+Layer 4
+[ ]
+Versions / snapshots / compare
+Essential for negotiation and signing history
+Layer 5
+[ ]
+Styles
+Needed for consistency and predictable structure
+Layer 4–5
+[ ]
+Revisions to formatting
+Must be visible if tracked changes claims are serious
+Layer 4
+[ ]
+Move tracking
+Useful in complex negotiations
+Layer 3–4
+[ ]
+Hyperlinks
+Lower risk, but should be preserved
+Layer 3
+[ ]
+Signature blocks
+High-value operationally, though often structurally simple
+Layer 4
+[ ]
+Pagination artifacts
+Important for print/export parity, less so for live editing
+Layer 3
+[ ]
+TOC / generated indexes
+Useful, but can be deferred
+Layer 2–3
+[ ]
+Embedded objects / OLE
+Usually low priority unless specific enterprise demand
+Layer 1–2
+[ ]
+Macros / advanced Word automation
+Usually out of scope initially
+Layer 0–1
+[ ]
+
+
+Element-by-element checklist
+1. Paragraphs and character runs
+Why it matters
+Everything else sits on top of this. Redlines, comments, clause numbering, and compare all depend on stable text ranges and block structure.
+Checklist
+Stable run segmentation
+Inline formatting preservation
+Reliable anchoring for comments and revisions
+Round-trip-safe text model
+Target fidelity reached: Layer 5
+
+2. Track changes / redlines
+Why it matters
+This is the main legal review interface.
+Checklist
+Insertions
+Deletions
+Formatting revisions
+Move operations, if supported
+Accept/reject at multiple scopes
+Author attribution
+Timestamp attribution
+Filter by reviewer or revision type
+First-class transaction and rendering system, not a visual diff hack
+Target fidelity reached: Layer 5
+
+3. Comments and comment threads
+Why it matters
+Lawyers negotiate through comment threads, not just edits.
+Checklist
+Anchoring to ranges, cells, rows, or structural objects
+Threading
+Resolve / reopen
+Mentions
+Assignment
+Export preservation
+Target fidelity reached: Layer 5
+
+4. Headings, clauses, and numbering
+Why it matters
+Legal documents depend heavily on precise structure and references.
+Checklist
+Stable heading hierarchy
+Clause identity separate from displayed number
+Automatic renumbering without broken references
+Number format preservation across import/export
+Target fidelity reached: Layer 5
+
+5. Lists and nested numbering
+Why it matters
+Indentation and numbering are often legally meaningful.
+Checklist
+Nested list support
+Mixed numbering formats
+Stable list item identity
+Redlines across list edits
+Target fidelity reached: Layer 5
+
+6. Tables
+Why it matters
+Tables often contain operative legal content, not layout fluff.
+Checklist
+Stable table identity
+Stable row identity
+Stable column identity
+Stable cell identity
+Merge / unmerge support
+Header row preservation
+Redlines inside cells
+Redlines on structural changes
+Comments on cells, rows, columns, and tables
+Good copy/paste behavior
+DOCX round-trip preservation
+Target fidelity reached: Layer 5
+
+7. Cross-references
+Why it matters
+Broken references destroy trust and can create real legal risk.
+Checklist
+Structural references, not just text
+Live update when section numbers move
+Broken-reference detection
+Navigation and preview
+Target fidelity reached: Layer 4–5
+
+8. Defined terms
+Why it matters
+Defined terms are one of the most important legal semantics in a contract.
+Checklist
+Identify definitions
+Link usages to definitions
+Highlight defined terms
+Detect undefined terms
+Detect inconsistent terms
+Jump-to-definition workflows
+Target fidelity reached: Layer 4
+
+9. Bookmarks and anchors
+Why it matters
+Needed for stable references, navigation, and comment/review resilience.
+Checklist
+Named anchors
+Stable mapping through edits
+Import/export preservation
+Target fidelity reached: Layer 4
+
+10. Styles
+Why it matters
+Consistency matters more than visual freedom in legal docs.
+Checklist
+Paragraph styles
+Character styles
+Style restrictions and validation
+Import/export mapping to DOCX styles
+Optional firm template support
+Target fidelity reached: Layer 4–5
+
+11. Formatting revisions
+Why it matters
+Formatting changes can affect interpretation or simply matter to legal teams.
+Checklist
+Capture tracked formatting changes
+Clear visibility in review mode
+Accept/reject behavior
+Target fidelity reached: Layer 4
+
+12. Versions, snapshots, and compare
+Why it matters
+Lawyers constantly compare drafts and need signable history.
+Checklist
+Snapshot versions
+Compare any two versions
+Audit trail
+Named draft states
+Pre-signature locking or snapshotting
+Target fidelity reached: Layer 5
+
+13. Metadata and document properties
+Why it matters
+Legal work depends on status and context.
+Checklist
+Document title
+Counterparty
+Status
+Jurisdiction
+Effective date
+Owner / internal matter reference
+Template linkage
+Playbook linkage
+Target fidelity reached: Layer 4
+
+14. Content controls / fields
+Why it matters
+Critical for template-driven legal generation and structured intake.
+Checklist
+Editable structured fields
+Validation rules
+Placeholder behavior
+Bound-value behavior
+DOCX mapping where feasible
+Target fidelity reached: Layer 4
+
+15. Sections and page setup
+Why it matters
+Important for exhibits, signature pages, headers, footers, page numbering, and print parity.
+Checklist
+Section breaks
+Page numbering rules
+Orientation preservation
+Margin preservation
+Export fidelity
+Target fidelity reached: Layer 4
+
+16. Headers and footers
+Why it matters
+Draft labels, confidentiality notices, and version marks often live here.
+Checklist
+Distinct first-page variants where needed
+Odd/even variants where needed
+Import/export mapping
+Limited editing UI
+Target fidelity reached: Layer 3–4
+
+17. Footnotes and endnotes
+Why it matters
+Used in some legal, policy, and regulatory documents.
+Checklist
+Stable note anchors
+Note editing
+Redlines involving note content
+Comments involving note content
+Export fidelity
+Target fidelity reached: Layer 4
+
+18. Hyperlinks
+Why it matters
+Usually lower legal risk, but they should behave predictably.
+Checklist
+Link preservation
+Click and edit
+Safe external navigation handling
+Target fidelity reached: Layer 3
+
+19. Images, shapes, and text boxes
+Why it matters
+They show up in exhibits, diagrams, and branded templates.
+Checklist
+Render reliably
+Preserve position sufficiently for export
+Basic selection support
+Replacement support
+Comment support
+Target fidelity reached: Layer 2–3
+
+20. Signature blocks
+Why it matters
+High operational value at the end of the workflow.
+Checklist
+Protected layout
+Role labels
+Signer metadata
+Export-safe structure
+Optional signature workflow integration later
+Target fidelity reached: Layer 4
+
+21. Permissions, locks, and protected ranges
+Why it matters
+Legal review is controlled collaboration, not chaos.
+Checklist
+Read rights
+Comment rights
+Edit rights
+Section locks
+Suggest-only mode
+Blocked edits to protected regions
+Target fidelity reached: Layer 4
+
+22. Pagination artifacts
+Why it matters
+Lawyers care about where things land in print and PDF, especially near signature pages, annexes, and references.
+Checklist
+Page breaks
+Keep-with-next where feasible
+Widow/orphan controls where feasible
+Draft print-preview mode
+Target fidelity reached: Layer 3
+
+23. TOC and generated indexes
+Why it matters
+Useful for longer agreements and policy packs.
+Checklist
+Generated table of contents from headings
+Refresh / regenerate behavior
+Export mapping where feasible
+Target fidelity reached: Layer 2–3
+
+24. Embedded objects / OLE / macros
+Why it matters
+They exist in Word ecosystems, but usually create complexity without enough value.
+Checklist
+Safe rendering placeholder
+Metadata preservation where possible
+Explicit unsupported-state UI
+Target fidelity reached: Layer 0–2
+
+Suggested implementation tiers
+Tier A — Must-have before calling it legal review
+Paragraphs and runs
+Track changes
+Comments
+Headings / clauses / numbering
+Lists and nested numbering
+Tables
+Versions / compare
+Tier B — Must-have before calling it a serious legal platform
+Cross-references
+Defined terms
+Styles
+Metadata
+Content controls / fields
+Permissions / locks
+Sections / page setup
+Signature blocks
+Tier C — Completeness and interoperability hardening
+Headers / footers
+Footnotes / endnotes
+Hyperlinks
+Images / shapes / text boxes
+Pagination controls
+TOC / generated indexes
+Tier D — Explicitly de-prioritized unless forced by customers
+Macros
+OLE embedded objects
+Advanced Word automation edge cases
+
+Product design recommendation checklist
+Build a strict structural document model
+Build a revision engine
+Build an anchoring and identity system
+Build a legal semantics layer for clauses, terms, references, tables, and permissions
+Build a DOCX translation layer on top
+Do not build this as a generic rich-text editor with Word import/export glued on
+Do not start HTML-first and try to bolt legal behavior on later
+
+Hard-truth checklist
+For this component to be credible for legal work:
+Meaning must survive structural edits
+Review must preserve traceability
+Collaboration must use stable anchors
+DOCX round-trip must not lose intent
+The true first-class objects are:
+Revisions
+Comments
+Clauses
+Numbering
+Tables
+References
+Definitions
+Versions
+Permissions
+
+

package/docs/reference/live-proof-waves.md

@@ -0,0 +1,199 @@
+---
+title: "Live Proof Waves"
+summary: "How to author proof-first `pilot-live` and higher-maturity waves with explicit proof artifacts, sticky executors, and operator-visible closure evidence."
+---
+
+# Live Proof Waves
+
+`pilot-live`, `fleet-ready`, `cutover-ready`, and `deprecation-ready` waves are not normal repo-only implementation waves.
+
+For the general runtime model behind helper requests, integration, and final staged closure, see [docs/reference/coordination-and-closure.md](./coordination-and-closure.md).
+
+For these waves:
+
+- operator-run commands are part of closure
+- local proof artifacts are part of closure
+- stale success is dangerous
+- sticky executors are safer than loose retry fallback
+- targeted reruns after new proof arrives are normal
+
+## Core Rule
+
+Repo-landed waves can stay repo-centric.
+
+`pilot-live` and above should be proof-centric.
+
+That means the wave should declare:
+
+- the exact proof owner
+- the exact operator command sequence
+- the exact artifact bundle written locally
+- the exact proof surfaces that closure should trust
+
+For a full authored example wave that uses this pattern, see [docs/reference/sample-waves.md](./sample-waves.md) and the linked proof-first live-wave sample.
+
+## Recommended Authoring Pattern
+
+For live-proof owners:
+
+- declare `### Deliverables` for the review/report surface
+- declare `### Proof artifacts` for machine-visible local evidence
+- keep the executor sticky unless fallback is explicitly required
+- prefer wall-clock budgets over tiny hard turn caps
+
+Example:
+
+````md
+## Agent A6: Learning Plane Live Validation
+
+### Executor
+
+- id: codex
+- retry-policy: sticky
+- budget.minutes: 30
+
+### Exit contract
+
+- completion: live
+- durability: durable
+- proof: live
+- doc-impact: owned
+
+### Deliverables
+
+- docs/plans/waves/reviews/wave-8-live-proof.md
+
+### Proof artifacts
+
+- path: .tmp/wave-8-learning-proof/learning-plane-before-restart.json | kind: live-status | required-for: pilot-live
+- path: .tmp/wave-8-learning-proof/learning-plane-after-restart.json | kind: restart-check | required-for: pilot-live
+- path: .tmp/wave-8-learning-proof/learning-vector-manifest.json | kind: manifest | required-for: pilot-live
+
+### Prompt
+```text
+Operator command sequence:
+- leapctl learning status --json > .tmp/wave-8-learning-proof/learning-plane-before-restart.json
+- leapctl learning restart ...
+- leapctl learning status --json > .tmp/wave-8-learning-proof/learning-plane-after-restart.json
+
+Closure only counts when the declared proof artifacts exist locally and match the claimed live state.
+
+File ownership (only touch these paths):
+- .tmp/wave-8-learning-proof/
+- docs/plans/waves/reviews/wave-8-live-proof.md
+```
+````
+
+## `### Proof artifacts`
+
+Use `### Proof artifacts` for the local machine-visible evidence that must exist before closure can trust a live claim.
+
+Supported shape:
+
+```md
+### Proof artifacts
+
+- path: .tmp/example/live-status.json | kind: live-status | required-for: pilot-live
+- path: .tmp/example/after-restart.json | kind: restart-check | required-for: pilot-live
+```
+
+Guidance:
+
+- keep artifact paths repo-relative
+- keep artifact paths inside the agent's owned paths
+- use one file per important proof surface
+- prefer canonical JSON or markdown artifacts over ad hoc screenshots or ephemeral terminal output
+
+## Retry And Executor Guidance
+
+For proof-bearing owners, default to sticky retry:
+
+```md
+### Executor
+
+- id: codex
+- retry-policy: sticky
+- budget.minutes: 45
+```
+
+Only enable cross-executor retry when there is a deliberate reason to do so.
+
+If you do allow fallback, declare it explicitly:
+
+```md
+### Executor
+
+- id: codex
+- retry-policy: fallback-allowed
+- fallbacks: claude
+```
+
+## What Closure Should Trust
+
+Closure roles should trust:
+
+- declared proof artifacts that exist locally
+- structured markers
+- integration summaries grounded in current artifacts
+
+Closure roles should not trust:
+
+- implied host state
+- stale cached snapshots
+- repo-local inference when the wave claims live proof
+- old `status=0` results that no longer match the current proof surface
+
+## Targeted Reruns
+
+When new proof artifacts arrive after an earlier failed attempt, the right response is usually a targeted rerun, not a full implementation replay.
+
+Typical pattern:
+
+1. operator captures the missing proof bundle locally
+2. operator can register that bundle directly:
+
+```bash
+pnpm exec wave control proof register \
+  --lane main \
+  --wave 8 \
+  --agent A6 \
+  --artifact .tmp/wave-8-learning-proof/learning-plane-before-restart.json \
+  --artifact .tmp/wave-8-learning-proof/learning-plane-after-restart.json \
+  --authoritative \
+  --satisfy-owned-components \
+  --completion live \
+  --durability durable \
+  --proof-level live \
+  --doc-delta owned \
+  --detail "Operator captured and verified restart evidence."
+```
+
+3. the proof owner reruns on the same executor only if additional synthesis is still needed
+4. any stale integration or closure owner reruns if needed
+5. already-valid implementation slices stay reused
+
+Authoritative proof registration is the supported way to make operator-produced evidence visible to A8, A0, rerun control, and hermetic traces without forcing an implementation agent to rediscover the same local artifacts in a fresh session. The canonical proof bundle now lands in `.tmp/<lane>-wave-launcher/control-plane/` and is projected into `.tmp/<lane>-wave-launcher/proof/` for compatibility.
+
+## Suggested Eval Targets For Live-Proof Waves
+
+Good live-proof waves often pair the proof owner with `cont-EVAL` targets that check coordination quality as well as service behavior.
+
+Useful examples:
+
+```md
+## Eval targets
+
+- id: blackboard-fidelity | selection: delegated | benchmark-family: blackboard-fidelity | objective: Preserve machine-visible proof through summaries and integration | threshold: Critical live proof facts remain visible through closure
+- id: contradiction-recovery | selection: pinned | benchmarks: claim-conflict-detection,evidence-based-repair | objective: Surface and repair conflicting live claims before PASS | threshold: Material contradictions become explicit repair work before final closure
+```
+
+## Promotion-Level Guidance
+
+- `pilot-live`
+  Require explicit proof artifacts and prefer sticky executors for proof owners.
+- `fleet-ready`
+  Require the `pilot-live` discipline plus stronger infra/deploy readiness evidence.
+- `cutover-ready`
+  Require the `fleet-ready` discipline plus explicit rollback or cutover evidence.
+
+The important principle is that higher maturity should mean stronger machine-visible proof, not just more prose.