@ansonlai/docx-redline-js 0.6.1 → 0.7.0

package/AGENTS.md

@@ -21,9 +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. 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
@@ -38,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
@@ -63,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 |
@@ -147,10 +163,13 @@ const inventory = inspectDocumentParts({ documentXml, commentsXml, numberingXml
 Inspection returns exact paragraph text, target IDs/fingerprints, headings,
 table/list context, revision authors, and joined comment anchors. Filters such
 as `search`, `indexes`, `range`, `revisedOnly`, `inTable`, and `skipEmpty`
-limit output. Search is a case-insensitive substring match; `around` adds nearby
-drafting context, while `limit` and `after` page direct hits. `revisionView`
-accepts `accepted`, `rejected`, or `current`. Returned paragraphs identify
-matches versus context and include `humanReference` for user-facing summaries.
+limit output. Search is a case-insensitive substring match; `around` adds nearby drafting
+context, while `limit` and `after` page direct hits. When a search yields 0
+matches in the active view, `selection.hint` provides guidance if matches exist
+in the alternate revision view (such as searching for deleted text to restore).
+`revisionView` accepts `accepted`, `rejected`, or `current`. Returned
+paragraphs identify matches versus context and include `humanReference` for
+user-facing summaries.
 
 For complete `.docx` buffers in Node:
 
@@ -212,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
@@ -249,25 +282,31 @@ 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
-budget when no explicit positional scope is supplied. Use `--limit` with
-`--after <paragraph-index>` to continue, `--around N` (aliases `--context` and
-`-C`) to include nearby paragraphs, and `--all` only for deliberate unbounded
-inspection. Every retained target is complete; an individually oversized
-paragraph is returned whole with an `oversizeItem` marker. Machine `index` and
-`ref` fields are for targeting and pagination, not user-facing Word locations;
-use `humanReference`, `provision`, or `nearestHeading` in reports.
+budget when no explicit positional scope is supplied. When a search returns 0
+matches in the requested view, `selection.hint` provides immediate guidance if
+matches exist in the alternate view (such as searching for a deleted clause to
+restore). Use `--limit` with `--after <paragraph-index>` to continue, `--around N`
+(aliases `--context` and `-C`) to include nearby paragraphs, and `--all` only
+for deliberate unbounded inspection. Every retained target is complete; an
+individually oversized paragraph is returned whole with an `oversizeItem`
+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, and compact examples.
+machine-readable options, behavior, exit codes, canonical GitHub documentation links, and compact examples.
 
 See the [compact agent fast start](./docs/AGENT_FAST_START.md), the
 [skill/harness authoring contract](./docs/SKILL_AUTHORING.md), and the

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

@@ -1,4 +1,4 @@
-// @ansonlai/docx-redline-js v0.6.1 — 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;
@@ -11594,6 +11594,34 @@ function inspectDocumentParts(parts, options = {}) {
     comments.set(id, definition);
   }
   const selected = selectInspectionParagraphs(paragraphs, options);
+  if (options.search && selected.selection && selected.selection.totalMatches === 0) {
+    const needle = String(options.search).toLowerCase();
+    const alternateView = revisionView === "accepted" ? "rejected" : "accepted";
+    let rangeStart = 1;
+    let rangeEnd = paragraphNodes.length;
+    if (options.range) {
+      rangeStart = Number(options.range.start ?? options.range[0]);
+      rangeEnd = Number(options.range.end ?? options.range[1]);
+    }
+    let alternateMatches = 0;
+    for (let i = 0; i < paragraphNodes.length; i++) {
+      const index = i + 1;
+      if (options.range && (index < rangeStart || index > rangeEnd)) continue;
+      if (Array.isArray(options.indexes) && !options.indexes.includes(index)) continue;
+      const pNode = paragraphNodes[i];
+      if (options.table && !hasAncestor(pNode, "tc")) continue;
+      if (options.body && hasAncestor(pNode, "tc")) continue;
+      if (options.revised && revisionAuthors(pNode).length === 0) continue;
+      const altText = extractCanonicalParagraphText(pNode, { revisionView: alternateView });
+      if (options.skipEmpty && altText.length === 0) continue;
+      if (altText.toLowerCase().includes(needle)) {
+        alternateMatches++;
+      }
+    }
+    if (alternateMatches > 0) {
+      selected.selection.hint = revisionView === "accepted" ? `0 matches in accepted view, but ${alternateMatches} match${alternateMatches === 1 ? "" : "es"} found in --view rejected. If searching for deleted text to restore, re-run with --view rejected.` : `0 matches in rejected view, but ${alternateMatches} match${alternateMatches === 1 ? "" : "es"} found in --view accepted. Re-run with --view accepted.`;
+    }
+  }
   paragraphs = selected.paragraphs;
   const allRevisionAuthors = [...new Set(paragraphs.flatMap((item) => item.revisionAuthors))].sort();
   const coveredEntries = extractDocumentPartsEntries(parts);