@beyondwork/docx-react-component 1.0.0 → 1.0.2

package/docs/reference/legal-checklist.md

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

@@ -1,199 +0,0 @@
----
-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.