@ansonlai/docx-redline-js 0.6.2 → 0.7.0

package/docs/schemas/document-operations.schema.json

@@ -38,6 +38,16 @@
       },
       "additionalProperties": false
     },
+    "localizedReplacement": {
+      "type": "object",
+      "required": ["find", "replace"],
+      "properties": {
+        "find": { "type": "string", "minLength": 1 },
+        "replace": { "type": "string" },
+        "occurrence": { "type": "integer", "minimum": 1 }
+      },
+      "additionalProperties": false
+    },
     "target": {
       "oneOf": [
         { "type": "string", "minLength": 1 },
@@ -99,6 +109,9 @@
           },
           "additionalProperties": false
         },
+        {
+          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["replacements"], "properties": { "type": { "enum": ["redline", "replace"] }, "replacements": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/localizedReplacement" } } } } ]
+        },
         {
           "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["modified"], "properties": { "type": { "enum": ["redline", "replace", "format", "list-change", "table-reconciliation", "insert"] }, "modified": { "type": "string" }, "structuredContent": { "type": "boolean" }, "targetEnd": { "$ref": "#/$defs/target" }, "targetEndRef": { "type": ["integer", "string", "null"] }, "anchor": { "$ref": "#/$defs/rejectedTextInsertionAnchor" } } } ]
         },

package/docs/validation-reports/2026-09-14-localized-patching-rollout.md

@@ -0,0 +1,90 @@
+# Localized Patching and Turn-Reduction Rollout Audit
+
+**Date:** 2026-09-14
+**Scope:** WP-05 correctness matrix and controlled workflow benchmark for CLI
+contract 8
+
+## Outcome
+
+The contract-8 literal fast path removes one of two tool turns and reduces the
+generated mutation request by roughly two-thirds to four-fifths in the measured
+cases. Native DOCX execution remains essentially the same speed: median changes
+ranged from 0.58% slower to 5.41% faster. This is the intended result—the
+feature attacks agent turn and output-generation latency without replacing the
+OOXML reconciliation or validation pipeline.
+
+All successful candidates produced the expected accepted-view text, positive
+localized change verification, and a byte-identical source document. Refused
+speculation remained non-writing in the automated suite.
+
+## Controlled comparison
+
+Run:
+
+```bash
+npm run benchmark:localized
+```
+
+The benchmark uses `tests/fixtures/sample_doc_test.docx`, 3 warmups, and 11
+measured iterations per workflow. Both paths run on the same current source
+tree to isolate workflow shape from runtime or machine drift:
+
+- **0.6.2-style baseline:** focused `extract`, followed by a canonical
+  full-paragraph operation.
+- **Contract-8 candidate:** targetless localized `apply`, either globally or
+  within a directional heading scope.
+
+| Case | Tool turns | Request bytes | Token proxy | Median local ms | p95 local ms |
+|---|---:|---:|---:|---:|---:|
+| Short punctuation, baseline → candidate | 2 → 1 | 244 → 79 | 61 → 20 | 55.34 → 53.37 | 83.89 → 62.11 |
+| Long provision, baseline → candidate | 2 → 1 | 352 → 123 | 88 → 31 | 58.02 → 54.88 | 70.04 → 59.44 |
+| Directional heading, baseline → candidate | 2 → 1 | 626 → 129 | 157 → 33 | 56.46 → 56.79 | 77.35 → 63.92 |
+
+Observed reductions:
+
+- Tool turns: **50%** in every case.
+- Generated request bytes: **65.06%–79.39%**.
+- Deterministic token proxy: **64.77%–78.98%**.
+- Median local engine/I/O time: **-0.58%–5.41%** (effectively neutral).
+- p95 local engine/I/O time: **15.13%–25.96% lower** in this run; timing is
+  observational and not a correctness gate.
+
+The directional candidate returned 20 more response bytes than its two-turn
+baseline because its one response includes explicit location and before/after
+verification. That small cost is intentional: it removes the verification turn
+while making the applied change auditable.
+
+## Measurement boundary
+
+`generatedTokenProxy` is `ceil(UTF-8 request bytes / 4)`. It is a deterministic
+comparison aid, not a provider tokenizer or billed-token count. Local timing
+uses `performance.now()` and includes DOCX reads, inspection, mutation,
+validation, and output writing.
+
+The benchmark does **not** measure model reasoning, token streaming, tool
+transport, network latency, or end-to-end Claude/OpenCode wall time. Those
+components require external harness transcript instrumentation and must not be
+inferred from native timing. The JSON artifact is written to
+`tmp/benchmarks/localized-turn-reduction-latest.json`.
+
+## Correctness coverage
+
+The expanded suites cover:
+
+- simultaneous localized replacements, ambiguity, deletion, no-op and overlap
+  rejection, unsupported v1 shapes, summary ordering, excerpt bounds, and
+  atomic rollback disposition;
+- global speculative success; `0:0`, `0:3`, `1:3`, `-3:-1`, and `-3:3`
+  directional windows; boundary clamping; repeated-anchor window deduplication;
+  missing anchors and patch sources; multi-paragraph and same-paragraph
+  ambiguity; occurrence scoping; stale IDs; protected outputs; response bounds;
+  and agent-profile exit behavior.
+
+## Verification
+
+- `npm test`: 113 suites passed, 0 failed with the expanded assertions.
+- `npm run check:types`: 123 runtime exports have declarations.
+- `npm run test:isolation`: dependency and Word-API isolation passed.
+- Focused ESLint for the localized compiler, CLI, benchmark, and tests passed.
+- `npm pack --dry-run --json`: 154 entries; the compiler and this report are
+  included, while the fixture-dependent benchmark script is excluded.

package/index.d.ts

@@ -23,6 +23,8 @@ export type {
   DocumentOperationBatchResult,
   HighlightDocumentOperation,
   InsertionAffinity,
+  LocalizedReplacement,
+  LocalizedReplacementChange,
   OperationConflict,
   OperationDependencyPlan,
   OperationPreflightItemResult,

package/node/cli-help.js

@@ -39,6 +39,14 @@ const APPLY_EXAMPLES = Object.freeze([
             modified: 'Revised clause.'
         }
     },
+    {
+        description: 'Localized tracked replacement in one strong accepted-view paragraph target.',
+        operation: {
+            type: 'redline',
+            target: { paragraphId: '1A2B3C4D' },
+            replacements: [{ find: 'thirty (30) days', replace: 'sixty (60) days' }]
+        }
+    },
     {
         description: 'Comment the complete target paragraph.',
         operation: {
@@ -116,7 +124,7 @@ export const CLI_COMMAND_HELP = Object.freeze({
     },
     apply: {
         summary: 'Apply canonical document operations and write a derived DOCX.',
-        usage: 'docx-redline apply <file.docx> --operations <file.json|-> [options]',
+        usage: 'docx-redline apply <file.docx> (--operations <file.json|->|<inline operation>) [options]',
         options: [
             HELP,
             option('operations', '--operations <file.json|->, --operations-file <file>', 'Read an operation array/envelope from a UTF-8 file or serializer-backed stdin.'),
@@ -124,7 +132,14 @@ export const CLI_COMMAND_HELP = Object.freeze({
             option('noClobber', '--no-clobber', 'Alias of --no-overwrite.'),
             option('expectedRevision', '--expected-revision <token|json>', 'Reject a stale package revision.'),
             option('target', '--target <text>', 'Inline one-operation target text.'),
+            option('targetId', '--target-id <paragraphId>', 'Strong inline target using a paragraphId from fresh inspection.'),
             option('modified', '--modified <text>', 'Complete desired accepted-view target content.'),
+            option('find', '--find <exact text>', 'Exact case-sensitive source span for one localized replacement.'),
+            option('replace', '--replace <text>', 'Replacement text for --find; an empty string deletes the span.'),
+            option('occurrence', '--occurrence <N>', 'Positive 1-based --find occurrence within the uniquely resolved target paragraph.'),
+            option('search', '--search <text>', 'Case-insensitive context anchor for speculative find/replace; all matching anchors are considered.'),
+            option('contextRange', '--context-range <START:END>', 'Signed inclusive paragraph offsets (-20..20) from each --search anchor; 1:3 means strictly the next three paragraphs.'),
+            option('around', '--around <N>', 'With --search, shorthand for symmetric --context-range -N:N (0-20).'),
             option('comment', '--comment <text>', 'Create an inline comment operation.'),
             option('textToComment', '--text-to-comment <text>', 'Anchor an inline comment to an exact subspan.'),
             option('targetRef', '--target-ref <N>', 'Disambiguate an inline target with a 1-based machine index.'),
@@ -138,6 +153,10 @@ export const CLI_COMMAND_HELP = Object.freeze({
         ],
         notes: [
             'modified is complete desired accepted-view content, not only inserted words.',
+            'Use either modified or find/replace. A strong accepted-view target is preferred when already known.',
+            'Without a strong target, find/replace may resolve globally or within --search plus a directional context range; it fails unless exactly one paragraph is eligible.',
+            '--occurrence disambiguates repeated text only within one uniquely selected paragraph, never between paragraphs.',
+            'Inline find/replace accepts one replacement; use operations JSON for multiple simultaneous replacements.',
             'Use a structured JSON file or serializer-backed stdin; never interpolate legal text through raw shell quoting.',
             'The source is never overwritten unless --in-place is explicit.',
             'The agent profile keeps progressive execution unless --atomic is explicit and does not change existing-revision policy.',
@@ -215,4 +234,3 @@ export function buildCliHelp(command = null) {
         documentation: [...CLI_DOCUMENTATION_URLS]
     };
 }
-

package/node/cli.js

@@ -10,7 +10,7 @@ import { normalizeErrorWithRecovery } from '../services/error-recovery.js';
 import { buildCliHelp, CLI_COMMANDS, commandOptionKeys } from './cli-help.js';
 
 const suffixes = { apply: 'redlined', accept: 'accepted', reject: 'rejected', 'delete-comments': 'comments-removed' };
-const CLI_CONTRACT_VERSION = 7;
+const CLI_CONTRACT_VERSION = 8;
 const DEFAULT_INSPECTION_LIMIT = 20;
 const INSPECTION_SOFT_BYTE_LIMIT = 48 * 1024;
 const CLI_CAPABILITIES = [
@@ -28,12 +28,25 @@ const CLI_CAPABILITIES = [
     'inspection-context-v1',
     'bounded-inspection-v1',
     'human-document-references-v1',
+    'localized-replacements-v1',
+    'speculative-search-apply-v1',
+    'localized-change-summary-v1',
     'deduplicated-cli-receipts',
     'compact-cli-json-v1'
 ];
 const commandOptions = Object.fromEntries(CLI_COMMANDS.map(command => [command, new Set(commandOptionKeys(command))]));
 
-function cliError(code, message, exitCode = 2, details) { return { status: 'error', error: normalizeErrorWithRecovery({ code, message, ...(details ? { details } : {}) }), exitCode }; }
+function cliError(code, message, exitCode = 2, details) {
+    return {
+        status: 'error',
+        error: normalizeErrorWithRecovery({
+            ...(details && typeof details === 'object' ? details : {}),
+            code,
+            message
+        }),
+        exitCode
+    };
+}
 const optionAliases = new Map([
     ['operationsFile', 'operations'],
     ['o', 'output'],
@@ -59,7 +72,7 @@ function parseArgs(argv) {
         const normalizedKey = rawKey.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
         const key = optionAliases.get(normalizedKey) || normalizedKey;
         if (inline !== undefined) flags[key] = inline;
-        else if (argv[index + 1] && (argv[index + 1] === '-' || !argv[index + 1].startsWith('-') || /^-\d/.test(argv[index + 1]))) flags[key] = argv[++index];
+        else if (argv[index + 1] !== undefined && (argv[index + 1] === '-' || !argv[index + 1].startsWith('-') || /^-\d/.test(argv[index + 1]))) flags[key] = argv[++index];
         else flags[key] = true;
     }
     return { command: positionals[0], input: positionals[1], extraPositionals: positionals.slice(2), flags };
@@ -150,31 +163,232 @@ async function readUtf8Stream(stream) {
     return Buffer.concat(chunks).toString('utf8');
 }
 
-async function readOperations(file, flags = {}, stdin = process.stdin) {
-    if (!file && flags?.target) {
-        let op;
-        if (flags.comment) {
-            op = {
-                type: 'comment',
-                target: String(flags.target),
-                commentContent: String(flags.comment),
-                ...(flags.textToComment ? { textToComment: String(flags.textToComment) } : {}),
-                ...(flags.targetRef ? { targetRef: positiveInteger(flags.targetRef) } : {}),
-                ...(flags.author ? { author: String(flags.author) } : {})
-            };
-        } else {
-            op = {
-                type: 'replace',
-                target: String(flags.target),
-                modified: flags.modified !== undefined ? String(flags.modified) : '',
-                ...(flags.targetRef ? { targetRef: positiveInteger(flags.targetRef) } : {}),
-                ...(flags.author ? { author: String(flags.author) } : {}),
-                ...(flags.existingRevisions ? { existingRevisions: String(flags.existingRevisions) } : {})
-            };
-        }
-        return { operations: [op], expectedRevision: null };
-    }
-    if (!file) throw Object.assign(new Error('Use --operations <file.json> or --target <text>.'), { code: 'OPERATIONS_REQUIRED' });
+function parseContextRange(value) {
+    const match = String(value).match(/^\s*(-?\d+)\s*:\s*(-?\d+)\s*$/);
+    if (!match) throw invalidFilter('--context-range must use START:END with signed integer offsets from -20 through 20.');
+    const start = Number(match[1]);
+    const end = Number(match[2]);
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < -20 || end > 20 || start > end) {
+        throw invalidFilter('--context-range requires START <= END and both offsets from -20 through 20.');
+    }
+    return { start, end, text: `${start}:${end}` };
+}
+
+function speculativeCandidate(paragraph) {
+    return {
+        excerpt: boundedText(paragraph.exactText, 240),
+        index: paragraph.index,
+        ref: paragraph.ref,
+        paragraphId: paragraph.paragraphId,
+        fingerprint: paragraph.fingerprint,
+        revisionView: 'accepted',
+        inTable: paragraph.inTable,
+        humanReference: paragraph.humanReference,
+        provision: paragraph.provision,
+        nearestHeading: paragraph.nearestHeading
+    };
+}
+
+function speculativeError(code, message, details = {}) {
+    return Object.assign(new Error(message), { code, ...details });
+}
+
+function resolveSpeculativePatchTarget(document, flags) {
+    if (!document) throw speculativeError('INVALID_OPERATION', 'Speculative localized replacement requires an open document.');
+    if (flags.contextRange !== undefined && flags.around !== undefined) {
+        throw invalidFilter('Use --context-range or --around, not both.');
+    }
+    const search = flags.search === undefined ? null : String(flags.search).trim();
+    if (flags.search !== undefined && (!search || flags.search === true)) {
+        throw invalidFilter('--search must be non-empty text.');
+    }
+    if ((flags.contextRange !== undefined || flags.around !== undefined) && !search) {
+        throw invalidFilter('--context-range and --around require --search.');
+    }
+    let range = { start: 0, end: 0, text: '0:0' };
+    if (flags.contextRange !== undefined) range = parseContextRange(flags.contextRange);
+    if (flags.around !== undefined) {
+        const text = String(flags.around).trim();
+        if (!/^\d+$/.test(text) || Number(text) > 20) {
+            throw invalidFilter('--around must be an integer from 0 through 20.');
+        }
+        const around = Number(text);
+        range = { start: -around, end: around, text: `${-around}:${around}` };
+    }
+
+    const inspected = document.inspect({ revisionView: 'accepted' });
+    const paragraphs = Array.isArray(inspected.paragraphs) ? inspected.paragraphs : [];
+    let anchors = [];
+    let eligible = paragraphs;
+    if (search) {
+        const folded = search.toLowerCase();
+        anchors = paragraphs.filter(paragraph => paragraph.exactText.toLowerCase().includes(folded));
+        if (anchors.length === 0) {
+            throw speculativeError('TARGET_NOT_FOUND', `No paragraph matched search query: "${search}".`, {
+                context: { search, range: range.text },
+                recovery: { action: 'reinspect', requiresReinspection: true, sameArgumentsSafe: false }
+            });
+        }
+        const eligibleIndexes = new Set();
+        for (const anchor of anchors) {
+            const anchorPosition = anchor.index - 1;
+            for (let offset = range.start; offset <= range.end; offset += 1) {
+                const position = anchorPosition + offset;
+                if (position >= 0 && position < paragraphs.length) eligibleIndexes.add(position);
+            }
+        }
+        eligible = [...eligibleIndexes].sort((a, b) => a - b).map(position => paragraphs[position]);
+    }
+
+    const find = String(flags.find);
+    const matches = eligible.filter(paragraph => paragraph.exactText.includes(find));
+    const context = {
+        ...(search ? { search, range: range.text, anchorMatchCount: anchors.length } : {})
+    };
+    if (matches.length === 0) {
+        throw speculativeError('PATCH_SOURCE_NOT_FOUND', search
+            ? `No paragraph in the contextual range contains the exact patch source: "${find}".`
+            : `No paragraph contains the exact patch source: "${find}".`, {
+            context,
+            ...(anchors.length ? { candidates: anchors.map(speculativeCandidate) } : {}),
+            recovery: { action: 'reinspect', requiresReinspection: true, sameArgumentsSafe: false }
+        });
+    }
+    if (matches.length > 1) {
+        throw speculativeError('AMBIGUOUS_TARGET', `The exact patch source matched ${matches.length} eligible paragraphs.`, {
+            context,
+            candidates: matches.map(speculativeCandidate),
+            recovery: { action: 'choose_candidate', requiresReinspection: false, sameArgumentsSafe: false }
+        });
+    }
+    const selected = matches[0];
+    return {
+        target: {
+            exactText: selected.exactText,
+            ...(selected.paragraphId ? { paragraphId: selected.paragraphId } : {}),
+            fingerprint: selected.fingerprint,
+            revisionView: 'accepted',
+            inTable: selected.inTable
+        },
+        context: {
+            ...context,
+            humanReference: selected.humanReference
+        }
+    };
+}
+
+async function readOperations(file, flags = {}, stdin = process.stdin, document = null) {
+    const hasInlineTarget = flags?.target !== undefined
+        || flags?.targetId !== undefined
+        || flags?.targetRef !== undefined;
+    const hasInlinePatch = flags?.find !== undefined
+        || flags?.replace !== undefined
+        || flags?.occurrence !== undefined;
+    const hasSpeculativeScope = flags?.search !== undefined
+        || flags?.contextRange !== undefined
+        || flags?.around !== undefined;
+    if (file && (hasInlinePatch || hasSpeculativeScope)) {
+        throw Object.assign(new Error('Use --operations or inline speculative find/replace options, not both.'), {
+            code: 'INVALID_OPERATION'
+        });
+    }
+    if (hasInlineTarget && hasSpeculativeScope) {
+        throw Object.assign(new Error('Use a strong inline target or --search/--context-range, not both.'), {
+            code: 'INVALID_OPERATION'
+        });
+    }
+    if (!file && (hasInlineTarget || hasInlinePatch || hasSpeculativeScope)) {
+        if (hasSpeculativeScope && !hasInlinePatch) {
+            throw Object.assign(new Error('--search, --context-range, and --around are only valid with inline --find/--replace.'), {
+                code: 'INVALID_OPERATION'
+            });
+        }
+        const targetRef = flags.targetRef === undefined ? null : positiveInteger(flags.targetRef);
+        if (flags.targetRef !== undefined && targetRef == null) {
+            throw Object.assign(new Error('--target-ref must be a positive 1-based integer.'), {
+                code: 'INVALID_OPERATION'
+            });
+        }
+        const targetId = flags.targetId === undefined ? null : String(flags.targetId).trim();
+        if (flags.targetId !== undefined && (!targetId || flags.targetId === true)) {
+            throw Object.assign(new Error('--target-id must be a non-empty paragraphId.'), {
+                code: 'INVALID_OPERATION'
+            });
+        }
+        const targetText = flags.target === undefined ? null : String(flags.target);
+        let target = targetId
+            ? { ...(targetText == null ? {} : { exactText: targetText }), paragraphId: targetId }
+            : targetText;
+        let speculativeContext = null;
+        let op;
+        if (flags.comment) {
+            if (hasInlinePatch) {
+                throw Object.assign(new Error('Inline comments cannot be combined with --find/--replace.'), {
+                    code: 'INVALID_OPERATION'
+                });
+            }
+            op = {
+                type: 'comment',
+                ...(target == null ? {} : { target }),
+                commentContent: String(flags.comment),
+                ...(flags.textToComment ? { textToComment: String(flags.textToComment) } : {}),
+                ...(targetRef == null ? {} : { targetRef }),
+                ...(flags.author ? { author: String(flags.author) } : {})
+            };
+        } else if (hasInlinePatch) {
+            if (flags.modified !== undefined) {
+                throw Object.assign(new Error('Use --modified or --find/--replace, not both.'), {
+                    code: 'INVALID_OPERATION'
+                });
+            }
+            if (
+                flags.find === undefined
+                || flags.find === true
+                || String(flags.find).length === 0
+                || flags.replace === undefined
+                || flags.replace === true
+            ) {
+                throw Object.assign(new Error('Inline localized replacement requires non-empty --find and string --replace values.'), {
+                    code: 'INVALID_OPERATION'
+                });
+            }
+            const occurrence = flags.occurrence === undefined ? null : positiveInteger(flags.occurrence);
+            if (flags.occurrence !== undefined && occurrence == null) {
+                throw Object.assign(new Error('--occurrence must be a positive 1-based integer.'), {
+                    code: 'INVALID_OPERATION'
+                });
+            }
+            if (!hasInlineTarget) {
+                const resolution = resolveSpeculativePatchTarget(document, flags);
+                target = resolution.target;
+                speculativeContext = resolution.context;
+            }
+            op = {
+                type: 'redline',
+                ...(target == null ? {} : { target }),
+                ...(targetRef == null ? {} : { targetRef }),
+                replacements: [{
+                    find: String(flags.find),
+                    replace: String(flags.replace),
+                    ...(occurrence == null ? {} : { occurrence })
+                }],
+                ...(speculativeContext ? { _speculativeContext: speculativeContext } : {}),
+                ...(flags.author ? { author: String(flags.author) } : {}),
+                ...(flags.existingRevisions ? { existingRevisions: String(flags.existingRevisions) } : {})
+            };
+        } else {
+            op = {
+                type: 'replace',
+                ...(target == null ? {} : { target }),
+                modified: flags.modified !== undefined ? String(flags.modified) : '',
+                ...(targetRef == null ? {} : { targetRef }),
+                ...(flags.author ? { author: String(flags.author) } : {}),
+                ...(flags.existingRevisions ? { existingRevisions: String(flags.existingRevisions) } : {})
+            };
+        }
+        return { operations: [op], expectedRevision: null };
+    }
+    if (!file) throw Object.assign(new Error('Use --operations <file.json> or an inline operation.'), { code: 'OPERATIONS_REQUIRED' });
     let parsed;
     try {
         const source = file === '-' ? await readUtf8Stream(stdin) : await readFile(file, 'utf8');
@@ -470,6 +684,11 @@ function compactMutationResult(value) {
     } = serialized;
     const results = Array.isArray(compact.results) ? compact.results.map(compactOperationResult) : [];
     const status = compact.status || 'ok';
+    const localizedChangesVerified = results.every(result => !result?.change || (
+        result.change.committed === true
+        && result.change.finalDisposition === 'applied'
+        && result.change.verification?.acceptedViewMatchesCompiledText === true
+    ));
     return {
         ...compact,
         ...(Array.isArray(compact.results) ? { results } : {}),
@@ -486,6 +705,7 @@ function compactMutationResult(value) {
             && status !== 'error'
             && status !== 'partial'
             && results.every(result => result?.status !== 'error')
+            && localizedChangesVerified
     };
 }
 
@@ -606,7 +826,7 @@ export async function executeCli(argv, io = process) {
             return { status: hasErrors ? 'error' : 'ok', command, input, valid: !hasErrors, issues };
         }
         const opsData = command === 'preflight' || command === 'apply'
-            ? await readOperations(flags.operations, flags, io.stdin || process.stdin)
+            ? await readOperations(flags.operations, flags, io.stdin || process.stdin, document)
             : null;
         const operations = opsData?.operations || null;
         let expectedRevision = opsData?.expectedRevision || null;
@@ -663,8 +883,13 @@ export async function executeCli(argv, io = process) {
                 generateRedlines,
                 ...(flags.existingRevisions ? { existingRevisions: flags.existingRevisions } : {}),
                 ...(expectedRevision ? { expectedRevision } : {})
-            });
-            const mutationResult = await writeMutation(command, input, flags, result);
+            });
+            const localizedVerificationFailed = (result.results || []).some(item => item?.change && (
+                item.change.committed !== true
+                || item.change.finalDisposition !== 'applied'
+                || item.change.verification?.acceptedViewMatchesCompiledText !== true
+            ));
+            const mutationResult = await writeMutation(command, input, flags, result);
             return compactMutationResult({
                 command,
                 input,
@@ -672,7 +897,7 @@ export async function executeCli(argv, io = process) {
                 ...(profile ? { executionProfile: profile, effectiveOptions } : {}),
                 ...(result.status === 'error'
                     ? { exitCode: 2 }
-                    : (result.status === 'partial' && requireComplete
+                    : ((result.status === 'partial' || localizedVerificationFailed) && requireComplete
                         ? { exitCode: 3 }
                         : {}))
             });
@@ -681,8 +906,8 @@ export async function executeCli(argv, io = process) {
         if (!filter) return cliError('AUTHOR_REQUIRED', 'Use --author <name> or --all-authors.');
         const result = command === 'delete-comments' ? await document.deleteComments(filter) : await document.resolveRevisions(command, filter);
         return compactMutationResult({ command, input, ...serializable(await writeMutation(command, input, flags, result)) });
-    } catch (error) { return cliError(error.code || 'CLI_FAILED', error.message); }
-}
+    } catch (error) { return cliError(error.code || 'CLI_FAILED', error.message, 2, error); }
+}
 
 export async function runCli(argv = process.argv.slice(2), io = process) {
     configureLogger({}, { level: 'silent' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ansonlai/docx-redline-js",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Host-independent OOXML reconciliation engine for .docx manipulation with track changes",
   "license": "MIT",
   "type": "module",
@@ -46,15 +46,18 @@
     "scripts/",
     "!scripts/benchmark-agent-workflow.mjs",
     "!scripts/benchmark-agent-cli-discovery.mjs",
+    "!scripts/benchmark-localized-turn-reduction.mjs",
     "!scripts/lib/agent-performance-cases.mjs",
     "docs/AGENT_FAST_START.md",
     "docs/AGENT_KNOWLEDGE_BASE.md",
     "docs/SKILL_AUTHORING.md",
     "docs/TESTING.md",
+    "docs/releases/0.7.0.md",
     "docs/schemas/document-operations.schema.json",
     "docs/validation-reports/2026-09-12-agent-protocol-rollout.md",
     "docs/validation-reports/2026-09-12-agent-cli-discovery-baseline.md",
     "docs/validation-reports/2026-09-13-agent-cli-efficiency-rollout.md",
+    "docs/validation-reports/2026-09-14-localized-patching-rollout.md",
     "index.js",
     "index.d.ts",
     "dist/",
@@ -93,6 +96,7 @@
     "benchmark:session": "node scripts/benchmark-operation-session.mjs",
     "benchmark:agent": "node scripts/benchmark-agent-workflow.mjs",
     "benchmark:agent-cli": "node scripts/benchmark-agent-cli-discovery.mjs",
+    "benchmark:localized": "node scripts/benchmark-localized-turn-reduction.mjs",
     "benchmark:targeting": "node scripts/benchmark-targeting-hot-paths.mjs",
     "benchmark:tests": "node scripts/benchmark-test-runner.mjs",
     "profile:routes": "node scripts/profile-route-selection.mjs",

package/services/batch-operation-orchestrator.js

@@ -450,8 +450,9 @@ export async function applyOperationsToDocumentXml(documentXml, operations, auth
                 authorUsed: result.authorUsed,
                 ...(result.resolvedBy ? { resolvedBy: result.resolvedBy } : {}),
                 ...(result.resolvedTarget ? { resolvedTarget: result.resolvedTarget } : {}),
-                ...(result.resolvedAnchor ? { resolvedAnchor: result.resolvedAnchor } : {}),
-                ...(Array.isArray(result.warnings) && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
+                ...(result.resolvedAnchor ? { resolvedAnchor: result.resolvedAnchor } : {}),
+                ...(result.change ? { change: result.change } : {}),
+                ...(Array.isArray(result.warnings) && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
                 ...(result.error ? { error: result.error } : {}),
                 ...(result.receipt ? { receipt: result.receipt } : {})
             });
@@ -531,26 +532,34 @@ export async function applyOperationsToDocumentXml(documentXml, operations, auth
         }
     }
 
-    if (rolledBack) {
-        for (const r of results) {
-            if (r.receipt && r.receipt.attemptedDisposition === 'applied') {
-                r.receipt.finalDisposition = 'rolled_back';
-                r.receipt.committed = false;
-            }
-        }
+    if (rolledBack) {
+        for (const r of results) {
+            if (r.receipt && r.receipt.attemptedDisposition === 'applied') {
+                r.receipt.finalDisposition = 'rolled_back';
+                r.receipt.committed = false;
+            }
+            if (r.change) {
+                r.change.finalDisposition = 'rolled_back';
+                r.change.committed = false;
+            }
+        }
         for (const receipt of allReceipts) {
             if (receipt.attemptedDisposition === 'applied') {
                 receipt.finalDisposition = 'rolled_back';
                 receipt.committed = false;
             }
         }
-    } else {
-        for (const r of results) {
-            if (r.receipt && r.receipt.attemptedDisposition === 'applied') {
-                r.receipt.committed = true;
-                r.receipt.finalDisposition = 'applied';
-            }
-        }
+    } else {
+        for (const r of results) {
+            if (r.receipt && r.receipt.attemptedDisposition === 'applied') {
+                r.receipt.committed = true;
+                r.receipt.finalDisposition = 'applied';
+            }
+            if (r.change) {
+                r.change.finalDisposition = 'applied';
+                r.change.committed = true;
+            }
+        }
         for (const receipt of allReceipts) {
             if (receipt.attemptedDisposition === 'applied') {
                 receipt.committed = true;