@ansonlai/docx-redline-js 0.6.2 → 0.7.0

package/AGENTS.md

@@ -21,10 +21,16 @@ specific advanced operation, API, or recovery topic you need.
 
 ## Ordinary document edits
 
-Use one focused extraction and one apply call. With a structured wrapper, use
-its revision-bound target handles. Follow `selection.hint` when a search for
-restorable text yields 0 matches in accepted view. For shell-only work, use a
-UTF-8 operations file or serializer-backed stdin and the explicit agent profile:
+For a literal mechanical edit with known old and new text, try one fail-closed
+apply call. Use a visible heading plus a directional range when global matching
+is too broad:
+
+```bash
+docx-redline apply contract.docx --search "Section 4.1" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+```
+
+For semantic drafting, inspect once and apply once. With a structured wrapper,
+use revision-bound handles. For shell-only work, use serializer-backed stdin:
 
 ```bash
 docx-redline extract contract.docx --search "termination" --around 3
@@ -39,10 +45,12 @@ Consolidate incompatible writes to the same source; use captures for intentional
 created-content dependencies.
 
 Require `completion: true`, `written: true`, a non-null output path, and no
-per-operation errors. Follow `error.recovery.action` and `retryPlan`; never retry
-unchanged failed arguments. Do not accept/reject another reviewer's work or
-remove comments without explicit user authorization. The source is never
-overwritten unless `--in-place` is explicit.
+per-operation errors. Localized edits also require `change.committed: true` and
+`change.verification.acceptedViewMatchesCompiledText: true`. Follow
+`error.recovery.action` and `retryPlan`; never retry unchanged failed arguments.
+Follow `selection.hint` for restorable text. Do not accept/reject another
+reviewer's work or remove comments without explicit user authorization. The
+source is never overwritten unless `--in-place` is explicit.
 
 The agent profile preserves progressive execution and the ordinary revision
 policy. Add `--atomic` or `--existing-revisions slice-cross-author` only when
@@ -64,7 +72,9 @@ targeting, revision allocation, comments, numbering, validation, or rollback.
 The stateful wrapper in `examples/agent-session-wrapper.mjs` is a testable
 development demonstration only. It is excluded from package files and exports.
 Production harnesses own their transport and negotiate the minimum CLI
-`contractVersion`/capabilities they use.
+`contractVersion`/capabilities they use. The 0.7.0 localized fast path requires
+contract 8 and its localized replacement, speculative apply, and change-summary
+capabilities.
 
 ## Code map
 

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 ## Unreleased
 
+## 0.7.0
+
+### Agent Performance and Localized Editing
+
+- **Localized exact replacements:** `redline`/`replace` operations may provide
+  `replacements: [{ find, replace, occurrence? }]` instead of a complete
+  `modified` paragraph. The compiler resolves the accepted-view source once,
+  applies non-overlapping exact replacements simultaneously, synthesizes the
+  canonical desired paragraph, and delegates to the unchanged OOXML engine.
+- **One-turn speculative apply:** `docx-redline apply --find ... --replace ...`
+  can resolve a globally unique source literal without preliminary extraction.
+  `--search` plus signed `--context-range START:END` scopes visible headings and
+  multi-paragraph provisions; `--around N` is symmetric shorthand.
+- **Fail-closed selection:** Missing anchors and patch sources, multiple eligible
+  paragraphs, ambiguous occurrences, overlaps, conflicts, and unsupported
+  localized shapes refuse mutation. A failed speculative command never writes
+  or truncates its output path.
+- **Verified change evidence:** Localized operation results include a compact
+  `change` object with target location, contextual anchor/range, exact
+  replacement entries, bounded before/after excerpts, commit disposition, and
+  post-mutation accepted-view verification. Atomic rollback marks the evidence
+  non-committed and `rolled_back`.
+- **CLI contract version 8:** Adds `localized-replacements-v1`,
+  `speculative-search-apply-v1`, and `localized-change-summary-v1`. Skills and
+  harnesses should pin version 0.7.0 and negotiate only the capabilities used.
+- **Measured workflow reduction:** The checked benchmark records 50% fewer tool
+  turns and a 64.77%–78.98% smaller deterministic request-token proxy across
+  three literal-edit cases. Median native engine/I/O time remained effectively
+  neutral; provider reasoning and network latency were not estimated.
+
+### Compatibility
+
+- Existing `modified` operations, strong targets, operations files/stdin,
+  tracked-change generation, package validation, rollback, comments,
+  Accept/Reject, and revision policies remain supported.
+- Localized replacement fields and successful `change` evidence are additive.
+  Wrappers that adopt them must require CLI contract 8; integrations using only
+  earlier capabilities can continue using their existing operation shapes.
+- The implementation remains OOXML-only and adds no runtime dependency or Word,
+  Office automation, COM, or proprietary document API requirement.
+
+## 0.6.0–0.6.2
+
 ### Safety Fixes
 
 - **Foreign deleted-paragraph resurrection guard**: Refuses non-empty same-paragraph edits when another author owns the paragraph-mark deletion and all existing paragraph content is deleted. The operation now returns `FOREIGN_PARAGRAPH_MARK_DELETION` with the owning author instead of emitting lifecycle-unsafe OOXML; atomic document operations roll back byte-for-byte. `validateRedlineOoxml` reports already-authored instances as warnings.

package/README.md

@@ -15,9 +15,25 @@ Converts AI-generated or programmatic text/markdown edits into valid Office Open
 - Comment management: delete comments by author or for all authors
 - Highlights: apply highlight colors to runs
 - Markdown and OOXML conversion in both directions
-- Status/error result fields for parse, targeting, and existing-revision failures
-- Package plumbing helpers for numbering.xml, comments.xml, content types, and relationships
-- Zero host dependencies: works in Node.js, browsers, Deno, and similar JS runtimes with DOM parsing support
+- Status/error result fields for parse, targeting, and existing-revision failures
+- Localized exact replacements and fail-closed one-turn CLI edits with verified before/after evidence
+- Package plumbing helpers for numbering.xml, comments.xml, content types, and relationships
+- Zero host dependencies: works in Node.js, browsers, Deno, and similar JS runtimes with DOM parsing support
+
+## What's New in 0.7.0
+
+Version 0.7.0 adds a contract-8 fast path for exact mechanical edits. Agents can
+send a small `find`/`replace` request instead of reproducing a complete legal
+paragraph, and may omit a strong target when the source literal resolves to one
+accepted-view paragraph. Visible headings can narrow the attempt with a signed
+directional window such as `--search "Section 4.1" --context-range 1:3`.
+
+Speculative edits fail without writing when the anchor, paragraph, or source
+span is missing or ambiguous. Successful localized results include a committed
+`change` object with the selected legal location, bounded before/after excerpts,
+and actual accepted-view verification. Existing full-paragraph operations,
+tracked-change semantics, validation, rollback, and review policies remain
+available unchanged. See the [complete 0.7.0 release notes](./docs/releases/0.7.0.md).
 ## Documentation Index
 
 | Document | Description |
@@ -215,9 +231,23 @@ benchmark explicitly does not claim to measure LLM reasoning or provider/tool
 latency. Checked comparative results are in the
 [agent protocol rollout audit](./docs/validation-reports/2026-09-12-agent-protocol-rollout.md).
 
+> **Pre-1.0 integration warning:** Agent skills, MCP servers, and harnesses
+> should pin the exact `@ansonlai/docx-redline-js` release they were tested
+> against and declare the CLI contract version/capabilities they require. Do
+> not treat a newly installed release or contract as verified until the
+> integration's compatibility tests pass. See the
+> [skill-authoring contract](./docs/SKILL_AUTHORING.md#runtime-negotiation).
+
 ### Agent CLI
-
+
 ```bash
+# One-turn exact mechanical edit; fails closed unless one paragraph matches
+docx-redline apply contract.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+
+# Directional context after a visible heading; repeated cross-references are safe
+docx-redline apply contract.docx --search "Section 4.1" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+
+# Semantic drafting still starts with focused context
 docx-redline extract contract.docx --search "termination" --around 3
 docx-redline preflight contract.docx --operations operations.json --author "Editor"
 docx-redline apply contract.docx --operations operations.json --author "Editor" --output reviewed.docx
@@ -252,6 +282,7 @@ All commands emit JSON on stdout. `apply` defaults:
 - **Compact stdout**: `--compact` emits one-line mutation JSON. It changes serialization only, not operation semantics.
 - **Tracked changes**: Defaults to `generateRedlines: true`. Pass `--no-redlines` when clean direct text edits are desired.
 - **Inline edits**: Use `--target <text>` with `--modified <text>` or `--comment <text>` for quick one-liners without creating a JSON file.
+- **Localized edits**: Use `--find`/`--replace` with a known strong target, or omit the target for fail-closed global resolution. Add `--search` with `--context-range 1:3` for text strictly after a visible heading; `--around 3` is symmetric. Successful localized results include bounded before/after excerpts and post-mutation accepted-view verification in `results[i].change`.
 - **Compact mutation results**: `apply`, `accept`, `reject`, and `delete-comments` omit full OOXML/package payloads and inspection text from stdout. CLI operation results omit duplicate nested receipt bodies; the ordered top-level `receipts` array is authoritative. Successful exact target-match diagnostics are omitted and equivalent-whitespace matches retain only mode/count. Node and standalone-runner results remain unchanged. Use `validate` when full issue arrays are needed.
 
 Inspection commands default to 20 direct matches and a 48 KiB soft response
@@ -266,12 +297,14 @@ marker. Machine `index` and `ref` fields are for targeting and pagination, not
 user-facing Word locations; use `humanReference`, `provision`, or
 `nearestHeading` in reports.
 
-`docx-redline version` reports contract version 7 and the additive
+`docx-redline version` reports contract version 8 and the additive
 `command-help-v1`, `inspection-context-v1`, `bounded-inspection-v1`,
 `human-document-references-v1`, `batch-start-source-binding`,
 `recovery-envelope-v1`, `require-complete-exit`, `operations-stdin`,
 `agent-safety-profile-v2`, `deduplicated-cli-receipts`, and
-`compact-cli-json-v1` capabilities. Wrappers should negotiate only the
+`compact-cli-json-v1`, `localized-replacements-v1`,
+`speculative-search-apply-v1`, and `localized-change-summary-v1` capabilities.
+Wrappers should negotiate only the
 capabilities they use. Run `docx-redline <command> --help` for that command's
 machine-readable options, behavior, exit codes, canonical GitHub documentation links, and compact examples.
 

package/dist/docx-redline-js.esm.js

@@ -1,4 +1,4 @@
-// @ansonlai/docx-redline-js v0.6.2 — https://github.com/AnsonLai/docx-redline-js
+// @ansonlai/docx-redline-js v0.7.0 — https://github.com/AnsonLai/docx-redline-js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;

package/docs/AGENT_FAST_START.md

@@ -7,53 +7,51 @@ Use this page for ordinary `.docx` edits. For source changes or unusual Word str
 If your host provides a document-session wrapper:
 
 1. Inspect/search once with enough surrounding context to draft the change.
-2. Apply using the returned revision-bound target handle. Send either the
-   complete desired paragraph or exact replacements supported by that wrapper.
-3. Treat only `ok: true` as complete. A failed handle must be refreshed by
-   inspection; never reuse it against a changed document.
+2. Apply with the revision-bound handle and complete desired text or exact replacements.
+3. Treat only `ok: true` as complete; refresh failed handles before reuse.
 
 The repository's `examples/agent-session-wrapper.mjs` demonstrates this pattern.
 It is a development sample, not a package API.
 
 ## CLI fallback
 
-1. Extract only the relevant clause or range:
+1. For a literal mechanical edit with known old and new text, try one-turn apply:
 
    ```bash
-   docx-redline extract contract.docx --search "termination" --around 3
+   docx-redline apply contract.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
    ```
 
-   Search is case-insensitive; follow `selection.hint` if 0 matches were found for restorable text. Direct hits are capped; follow `selection.nextAfter` with `--after`, and cite `humanReference`, not `P42`.
+   The source must occur in one eligible paragraph. For text after a heading, add `--search "Section 4.1" --context-range 1:3`.
+   `--around 3` is symmetric; use it only when either side is eligible.
+
+2. For semantic drafting such as “make this provision mutual,” extract enough
+   context, then copy `exactText` with `paragraphId` or `fingerprint`:
+
+   ```bash
+   docx-redline extract contract.docx --search "termination" --around 3
+   ```
 
-2. Copy `exactText` with `paragraphId` or `fingerprint`. Use a UTF-8 operations
-   file or serializer-backed stdin, then apply once:
+   Search is case-insensitive; follow `selection.hint` and `selection.nextAfter`, and report `humanReference`. Apply once with a UTF-8 operations file or serializer-backed stdin:
 
    ```bash
    node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
    ```
 
-   `emit-operations.mjs` should use `JSON.stringify`; do not interpolate legal
-   text through shell quoting. `modified` is the complete desired accepted-view
-   paragraph, not only the inserted words.
+   Use `JSON.stringify`, not shell interpolation. `modified` is the complete desired accepted-view paragraph.
 
 The `agent` profile preserves progressive execution and the ordinary revision policy while making incomplete work exit nonzero. Add `--atomic` deliberately; check `effectiveOptions`. Run `docx-redline apply --help` for redline, comment, and rejected-view restore shapes.
 
 ## Batch and result rules
 
-- Strong inspected targets are bound to the batch-start document. Independent
-  edits do not need bottom-up sorting around earlier paragraph splits.
-- Consolidate multiple desired texts for the same source paragraph. Follow an
-  explicit capture dependency for non-unique content created earlier in a batch.
+- Strong inspected targets bind to the batch start; independent edits need no bottom-up sorting.
+- Consolidate writes to one source; use captures for created-content dependencies.
 - Require `completion: true`, `written: true`, a non-null `outputPath`, and no
-  per-operation error. The source is not overwritten unless `--in-place` is
-  explicit.
+  per-operation error. For localized edits also require `change.committed: true`
+  and `change.verification.acceptedViewMatchesCompiledText: true`. The source is
+  not overwritten unless `--in-place` is explicit.
 - On failure, follow `error.recovery.action`. Never retry unchanged arguments.
-- `retryPlan.base: "original"` means correct and replay the complete batch.
-  `base: "output"` means keep committed progressive work and retry only the
-  reported failed or unattempted indexes.
-- Never accept/reject revisions or remove comments without user authorization.
-  `slice-cross-author` is the history-preserving option for a surgical edit
-  inside another reviewer's pending insertion.
+- `retryPlan.base: "original"` means replay the batch; `"output"` means retain committed work and retry reported indexes.
+- Never accept/reject revisions or remove comments without user authorization. `slice-cross-author` preserves history for edits inside foreign insertions.
 
 Advanced operations and recovery: [Agent Knowledge Base](AGENT_KNOWLEDGE_BASE.md); canonical contract: [document-operations.schema.json](schemas/document-operations.schema.json)  
 Wrapper design: [README](../README.md#example-agent-session-wrapper-development-only)

package/docs/AGENT_KNOWLEDGE_BASE.md

@@ -482,20 +482,26 @@ Use this for everything by default. `apply` is fast, progressive, and self-valid
 
 The short route for a document-editing request is:
 
-1. Run one focused `extract` for the clauses or range being edited. Search is a
-   case-insensitive substring match; add `--around 3` when surrounding drafting
-   context is needed. Copy `exactText` plus `paragraphId` or `fingerprint`.
-2. Build the final operations from the operation table above. Use one operation
+1. For an exact mechanical change with known old and new literals, use localized
+   `--find`/`--replace`. Omit the target for global fail-closed resolution, or
+   scope a visible heading with `--search` and a directional range such as
+   `--context-range 1:3`. Repeated anchor matches are unioned; one eligible patch
+   paragraph is still required. `--occurrence` selects only within that paragraph.
+2. For semantic drafting, run one focused `extract`. Add `--around 3` when
+   surrounding context on either side is needed, then copy `exactText` plus
+   `paragraphId` or `fingerprint`.
+3. Build the final operations from the operation table above. Use one operation
    per target paragraph, and consolidate multiple changes to that paragraph.
-3. Run `apply` once per stable batch. Strong inspected targets are bound against
+4. Run `apply` once per stable batch. Strong inspected targets are bound against
    the batch-start document, so independent operations do not need manual
    bottom-up sorting around structural edits. Consolidate multiple complete
    desired states for the same source. A unique exact reference to paragraph
    text created elsewhere in the batch is scheduled automatically; use explicit
    captures/selectors for non-unique or advanced created-content dependencies.
-4. Walk every result and require `completion: true`, `written: true`, and no
-   per-operation error.
-5. Run a focused `extract` on changed clauses only when placement or list/table
+5. Walk every result and require `completion: true`, `written: true`, and no
+   per-operation error. For localized patches also require committed `change`
+   evidence and positive accepted-view verification.
+6. Run a focused `extract` on changed clauses only when placement or list/table
    structure needs confirmation.
 
 Do not probe operation behavior with disposable apply commands or read a vendor
@@ -503,22 +509,28 @@ bundle before this route. If `apply` returns an error, use the recovery matrix
 below and make one cause-specific correction.
 
 ```bash
-# 1. Focused contextual discovery
+# 1. Globally unique mechanical edit in one call
+docx-redline apply contract.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+
+# 2. Mechanical edit strictly within three paragraphs after a visible heading
+docx-redline apply contract.docx --search "Section 4.1" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+
+# 3. Focused contextual discovery for semantic drafting
 docx-redline extract contract.docx --search "termination" --around 3
 
-# 2. Inline one-liner edit (fastest for 1–2 edits; no JSON file needed)
+# 4. Inline complete-paragraph edit
 docx-redline apply contract.docx --target "Original clause" --modified "New clause" --output reviewed.docx
 
-# 3. Direct edit without tracked changes (clean text, no revision clutter)
+# 5. Direct edit without tracked changes (clean text, no revision clutter)
 docx-redline apply contract.docx --target "Typo fix" --modified "Fixed typo" --no-redlines --output clean.docx
 
-# 4. Cross-author edit inside another reviewer's pending insertion
+# 6. Cross-author edit inside another reviewer's pending insertion
 docx-redline apply contract.docx --target "Pending clause text" --modified "Updated clause text" --existing-revisions slice-cross-author --output reviewed.docx
 
-# 5. Batch operations with ops.json
+# 7. Batch operations with ops.json
 docx-redline apply contract.docx --operations operations.json --output reviewed.docx
 
-# 6. Serializer-backed stdin with compact stdout
+# 8. Serializer-backed stdin with compact stdout
 node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
 ```
 

package/docs/SKILL_AUTHORING.md

@@ -4,6 +4,31 @@ Use this page when creating or updating an agent skill, MCP server, or custom
 harness for `@ansonlai/docx-redline-js`. Ordinary document-editing agents should
 load [Agent Fast Start](AGENT_FAST_START.md), not this design contract.
 
+> [!WARNING]
+> Before 1.0, every skill or harness must identify and pin its exact tested
+> library release and required CLI contract/capabilities. Treat any different
+> release or contract as unverified until compatibility tests pass.
+
+For example, an integration authored for the current contract-8 release should
+record a compatibility declaration equivalent to:
+
+```json
+{
+  "testedLibraryRelease": "0.7.0",
+  "requiredCliContractVersion": 8,
+  "requiredCapabilities": [
+    "command-help-v1",
+    "recovery-envelope-v1",
+    "localized-replacements-v1",
+    "speculative-search-apply-v1",
+    "localized-change-summary-v1"
+  ]
+}
+```
+
+The package pin anchors the release; runtime negotiation proves the executable
+exposes the required contract. A new release cannot inherit an old claim.
+
 ## Runtime negotiation
 
 Run this before the first document operation when the skill vendors or invokes
@@ -13,14 +38,11 @@ the CLI:
 docx-redline version
 ```
 
-Require contract version 7 and only the capabilities the integration uses. A
-typical shell skill should require `command-help-v1`, `inspection-context-v1`,
-`bounded-inspection-v1`, `human-document-references-v1`,
+Require contract version 8 (the currently declared contract) and only the
+capabilities the integration uses. A typical shell skill should require
 `agent-safety-profile-v2`, `deduplicated-cli-receipts`, and
-`recovery-envelope-v1`. Require `operations-stdin` or `compact-cli-json-v1` only
-when the host uses those features. Fail closed with an upgrade instruction when
-a required capability is absent. Never inspect `dist/`, minified source, or ZIP
-parts to compensate for a stale runtime.
+`recovery-envelope-v1`. Require other capabilities only when used. Fail closed
+when one is absent; never inspect bundles or ZIP parts as a fallback.
 
 ## Safety invariants
 
@@ -52,14 +74,6 @@ Choose and document these separately from safety invariants:
 | Reviewer identity | flag, operation author, environment, or fallback | `AI Redliner` is a valid visible fallback. `DOCX_REDLINE_AUTHOR` is an optional harness preference, not a guard. |
 | Output naming | derived sibling or explicit destination | Keep source immutability unless in-place mutation is deliberately authorized. |
 
-Examples of valid profile composition:
-
-```bash
-docx-redline apply input.docx --operations operations.json --profile agent --output reviewed.docx
-docx-redline apply input.docx --operations operations.json --profile agent --atomic --output reviewed.docx
-docx-redline apply input.docx --operations operations.json --profile agent --existing-revisions slice-cross-author --output reviewed.docx
-```
-
 Check `effectiveOptions` rather than assuming the resolved transaction,
 revision, author, or redline policy.
 
@@ -80,11 +94,26 @@ return the full structured result rather than recreating the CLI serializer.
 
 ## Ordinary generated workflow
 
-The first executable document-editing example in a generated skill should be a
-focused contextual extraction:
+For an exact mechanical edit whose existing and replacement literals are known,
+the first executable example should use the one-turn fast path:
+
+```bash
+docx-redline apply input.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+```
+
+If the literal is not globally unique, scope it with a meaningful visible
+anchor. A heading followed by a multi-paragraph provision should use a
+directional window such as `--search "Section 4.1" --context-range 1:3`;
+`--around 3` is symmetric and should be used only when either side is eligible.
+Require the returned localized `change` evidence, including `committed: true`
+and `verification.acceptedViewMatchesCompiledText: true`.
+
+Semantic requests such as “make this provision mutual” still begin with focused
+contextual extraction because the agent must identify and draft the complete
+legal change:
 
 ```bash
-docx-redline extract input.docx --search "force majeure" --around 3
+docx-redline extract input.docx --search "termination" --around 3
 ```
 
 Use `selection.nextAfter` with `--after` when truncated. When a search for
@@ -119,8 +148,15 @@ an exact machine target with a human-facing reference.
 
 ## Generation checklist
 
+- The exact tested library release is recorded and pinned; floating installs
+  are rejected while the library remains before 1.0.
+- The required CLI contract version and minimum capability set are declared,
+  checked at runtime, and updated only after compatibility tests pass.
 - Runtime version and required capabilities are checked once.
-- The first ordinary edit command is focused `extract --search ... --around`.
+- Literal edits use localized replacements and one-turn speculative apply;
+  semantic drafting starts with focused extraction.
+- Successful localized edits require committed, post-mutation `change`
+  verification before completion is reported.
 - Safety invariants are not mixed with transaction or revision-policy choices.
 - Operations-file and stdin examples use structured serialization.
 - The four-field recovery contract precedes any diagnostic commentary.

package/docs/releases/0.7.0.md

@@ -0,0 +1,199 @@
+## @ansonlai/docx-redline-js v0.7.0
+
+Version 0.7.0 targets the remaining latency in AI-driven document editing: tool
+turns and generated paragraph text. It adds exact localized replacements,
+fail-closed one-turn apply, directional provision scoping, and compact verified
+change evidence while retaining the existing OOXML mutation pipeline.
+
+The engine remains OOXML-only and host-independent. This release adds no runtime
+dependency and does not require Microsoft Word, Office automation, COM, or a
+proprietary document API. Existing reconciliation, tracked-change generation,
+package validation, rollback, comment preservation, and Accept/Reject semantics
+remain authoritative.
+
+---
+
+### Breaking Changes & Migration
+
+- **CLI contract version 8:** Wrappers using the new fast path should require
+  `localized-replacements-v1`, `speculative-search-apply-v1`, and
+  `localized-change-summary-v1`. Negotiate only the capabilities actually used.
+- **Pre-1.0 integration pinning:** Skills, MCP servers, and harnesses should pin
+  the exact `0.7.0` package release they tested and declare contract 8 plus their
+  minimum capability set. Treat another release or contract as unverified until
+  compatibility tests pass.
+- **No operation-shape removal:** Existing operations with complete `modified`
+  content continue to work. Localized replacements and `change` results are
+  additive; consumers ignoring unknown result fields remain compatible.
+
+---
+
+### 1. Localized Exact Replacements
+
+A text operation can now provide exact replacement instructions instead of
+reproducing the complete paragraph:
+
+```json
+{
+  "type": "redline",
+  "target": { "paragraphId": "1A2B3C4D" },
+  "replacements": [
+    {
+      "find": "thirty (30) days",
+      "replace": "sixty (60) days"
+    }
+  ]
+}
+```
+
+The compiler resolves the source paragraph against the immutable batch-start
+accepted view, applies non-overlapping patches simultaneously, synthesizes the
+complete desired text, and passes it through the ordinary reconciliation,
+validation, receipt, and rollback pipeline.
+
+V1 is deliberately narrow:
+
+- one accepted-view paragraph;
+- exact, case-sensitive source matching;
+- optional positive, 1-based `occurrence` within that paragraph;
+- an empty `replace` may delete a span;
+- ambiguous, missing, no-op, overlapping, or conflicting patches fail before
+  mutation; and
+- captures, rejected-view mutation, created-content dependencies, and
+  cross-paragraph patches remain outside localized-replacement v1.
+
+### 2. One-Turn Speculative Apply
+
+Globally unique literal edits no longer require preliminary extraction:
+
+```bash
+docx-redline apply contract.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+```
+
+For a heading followed by a multi-paragraph provision, use a visible text anchor
+and directional paragraph scope:
+
+```bash
+docx-redline apply contract.docx --search "Section 4.1" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+```
+
+`1:3` means strictly the next three physical paragraphs, excluding the heading
+and preceding paragraphs. Other supported forms include `0:0`, `0:3`,
+`-3:-1`, and `-3:3`; offsets are inclusive, bounded to `-20..20`, and clamped at
+document boundaries. `--around 3` is shorthand for `-3:3`.
+
+Every matching search anchor contributes a window. The library unions and
+deduplicates those windows, then requires exactly one eligible paragraph to
+contain the exact `find` literal. Thus a visible section number may appear both
+as a heading and in cross-references without the anchor itself deciding what is
+edited. `--occurrence` may disambiguate only inside the uniquely selected
+paragraph; it never chooses between paragraphs.
+
+### 3. Refusal Without Output Damage
+
+Speculation remains conservative:
+
+- no contextual anchor returns `TARGET_NOT_FOUND`;
+- no exact patch source returns `PATCH_SOURCE_NOT_FOUND`;
+- multiple eligible paragraphs return `AMBIGUOUS_TARGET`;
+- multiple source spans within one paragraph return
+  `AMBIGUOUS_PATCH_SOURCE`; and
+- invalid ranges and mixed targeting forms return a request error.
+
+These failures include machine recovery metadata and bounded candidates. They
+occur before output writing, so an existing destination is not truncated or
+overwritten. The source remains immutable unless `--in-place` is explicit.
+
+### 4. Explicit Post-Mutation Change Evidence
+
+Successful localized operations return a compact evidence object:
+
+```json
+{
+  "change": {
+    "kind": "localized_replacement",
+    "committed": true,
+    "finalDisposition": "applied",
+    "target": {
+      "paragraphId": "1A2B3C4D",
+      "humanReference": "Section 4.1 — Termination"
+    },
+    "context": {
+      "search": "Section 4.1",
+      "range": "1:3",
+      "anchorMatchCount": 2
+    },
+    "replacements": [
+      {
+        "find": "thirty (30) days",
+        "replace": "sixty (60) days",
+        "beforeExcerpt": "...thirty (30) days...",
+        "afterExcerpt": "...sixty (60) days..."
+      }
+    ],
+    "verification": {
+      "acceptedViewMatchesCompiledText": true
+    }
+  }
+}
+```
+
+Evidence is derived from the resolved source and actual post-mutation accepted
+view rather than simply echoing the request. Excerpts are deterministically
+bounded to 120 characters. Agent completion additionally requires committed,
+applied evidence and positive accepted-view verification. Atomic rollback marks
+previously attempted evidence `committed: false` and `rolled_back`.
+
+### 5. Agent Guidance and Development Wrapper
+
+- Agent Fast Start, the repository launch card, Skill Authoring Contract,
+  README, CLI help, and the advanced knowledge base now distinguish exact
+  mechanical edits from semantic drafting.
+- Literal names, dates, numbers, defined terms, and isolated phrase changes can
+  use localized one-turn apply. Semantic requests such as “make this provision
+  mutual” still begin with focused extraction and drafting.
+- The skill-authoring contract warns pre-1.0 integrations to pin the exact
+  package release and required CLI contract/capabilities.
+- `examples/agent-session-wrapper.mjs` remains a development-only illustration,
+  not a package export or alternate mutation engine.
+
+---
+
+### Performance Results
+
+The controlled `npm run benchmark:localized` comparison uses the same runtime
+for both paths, with 3 warmups and 11 measured iterations per case:
+
+- tool turns fell from 2 to 1 (**50% reduction**);
+- generated request bytes fell **65.06%–79.39%**;
+- the deterministic request-token proxy fell **64.77%–78.98%**; and
+- median native engine/I/O time ranged from **0.58% slower to 5.41% faster**,
+  confirming that the intended savings are primarily outside the OOXML engine.
+
+The token proxy is `ceil(UTF-8 request bytes / 4)`, not a provider tokenizer or
+billed-token measurement. Provider reasoning, streaming, network, and full
+Claude/OpenCode wall time were not estimated. See the
+[localized rollout audit](../validation-reports/2026-09-14-localized-patching-rollout.md).
+
+### Verification
+
+- `npm test`: **113 passed, 0 failed**
+- `npm run check:types`: declarations verified for **123 runtime exports**
+- `npm run test:isolation`: dependency and Word-API isolation passed
+- Focused CLI/compiler/test/benchmark lint: passed
+- Package dry run: compiler and published guidance included; development-only
+  benchmark and wrapper excluded
+
+---
+
+### Installation
+
+```bash
+npm install @ansonlai/docx-redline-js@0.7.0
+```
+
+CDN (ESM):
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@ansonlai/docx-redline-js@0.7.0/dist/docx-redline-js.esm.min.js"></script>
+```