@ansonlai/docx-redline-js 0.5.4 → 0.6.1

package/docs/SKILL_AUTHORING.md

@@ -0,0 +1,126 @@
+# Skill and Harness Authoring Contract
+
+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.
+
+## Runtime negotiation
+
+Run this before the first document operation when the skill vendors or invokes
+the CLI:
+
+```bash
+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`,
+`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.
+
+## Safety invariants
+
+Every generated integration must preserve these rules:
+
+- Inspect narrowly and copy `exactText` plus `paragraphId` or `fingerprint`.
+- Treat `modified` as the complete desired accepted-view target content.
+- Use strict targeting, package validation, and a derived output path; never
+  overwrite the source unless the caller explicitly requests `--in-place`.
+- Require `completion: true`, `written: true`, a non-null `outputPath`, and no
+  per-operation error before reporting completion.
+- Never accept or reject another reviewer's work or delete comments without
+  explicit user authorization.
+- Never retry unchanged failed arguments.
+
+The `agent` profile enables complete-success exit behavior and retains the
+ordinary progressive default. It does not select atomic execution or a special
+existing-revision policy. A skill must state those choices explicitly when its
+workflow needs them.
+
+## Workflow policy choices
+
+Choose and document these separately from safety invariants:
+
+| Choice | Options | Guidance |
+|---|---|---|
+| Transaction | progressive default or `--atomic` | Use progressive for independent edits; use atomic when partial output is unacceptable. |
+| Existing revisions | `merge-same-author` default or explicit policy | Use `slice-cross-author` only when editing inside another reviewer's pending insertion is intended. |
+| 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.
+
+## Transport choices
+
+A UTF-8 operations file and serializer-backed stdin are peer transports. Choose
+the form the host can construct safely:
+
+```bash
+docx-redline apply input.docx --operations operations.json --profile agent --output reviewed.docx
+node emit-operations.mjs | docx-redline apply input.docx --operations - --profile agent --compact --output reviewed.docx
+```
+
+Use `JSON.stringify` or a structured tool API. Never demonstrate `echo`, a
+heredoc, or shell-interpolated legal text. `--compact` changes stdout formatting,
+not result semantics. A Node byte-oriented wrapper should call `openDocx` and
+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:
+
+```bash
+docx-redline extract input.docx --search "force majeure" --around 3
+```
+
+Use `selection.nextAfter` with `--after` when truncated. Apply once per stable
+batch. Run `docx-redline apply --help` for canonical redline, whole-paragraph
+comment, and rejected-view restore shapes; the operation schema remains
+[document-operations.schema.json](schemas/document-operations.schema.json).
+
+## Recovery contract
+
+Lead error handling with exactly these runtime fields:
+
+1. `error.recovery.action`
+2. `error.recovery.requiresReinspection`
+3. `error.recovery.requiresUserAuthorization`
+4. `error.recovery.sameArgumentsSafe`
+
+Use `retryPlan.base` and its operation indexes to select the original or partial
+output package. Do not generate a second prose decision tree for every error
+code; error messages and bounded diagnostics explain the cause, while the four
+fields above determine the next action.
+
+## Presentation rules
+
+Use `humanReference`, `provision`, or `nearestHeading` in user-facing completion
+reports. `P55`, `index: 55`, and phrases such as “the 55th paragraph” are machine
+targeting and pagination coordinates, not locations a Word user can follow.
+When no formal heading exists, use the returned short text lead. Never replace
+an exact machine target with a human-facing reference.
+
+## Generation checklist
+
+- Runtime version and required capabilities are checked once.
+- The first ordinary edit command is focused `extract --search ... --around`.
+- 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.
+- Completion prose uses legal references rather than machine ordinals.
+- The wrapper delegates mutation, validation, rollback, comments, numbering,
+  receipts, and OOXML packaging to the library.

package/docs/TESTING.md

@@ -22,7 +22,10 @@ fixtures rarely contain.
 | Multimodal LLM visual spot check | On-demand / sampled | Evaluates rendered real-document pages with vision models for layout, table alignment, and typography regressions | Full-corpus automated coverage (intentionally decoupled and sampled due to cost/time) |
 | XSD and LibreOffice | See [Release validation and independent oracles](#release-validation-and-independent-oracles) | Schema conformance and acceptance by a second consumer | Word-specific revision semantics |
 | Agent inspection and package facade | `node tests/document_inspection_tests.mjs`, `node tests/docx_package_facade_tests.mjs` | Canonical text, comment/list resolution, package-scoped IDs, untouched-part preservation, and atomic rollback | Desktop Word rendering |
-| Agent CLI | `node tests/agent_cli_tests.mjs` | JSON contracts, exact-text extraction, author requirements, safe output behavior, all command families, and operation-schema readability | Cross-platform CI beyond the current runner |
+| Agent CLI | `node tests/agent_cli_tests.mjs`, `node tests/agent_cli_protocol_tests.mjs`, `node tests/agent_cli_help_tests.mjs`, `node tests/agent_cli_inspection_context_tests.mjs`, `node tests/agent_cli_output_budget_tests.mjs` | JSON contracts, command-specific help, contextual pagination, composable progressive/atomic profiles, deduplicated receipts, compact stdout, file/stdin Unicode fidelity, complete-success exits, source safety, command families, and schema readability | Cross-platform CI beyond the current runner |
+| Example agent session | `node tests/agent_session_example_tests.mjs`, `node tests/localized_edit_example_tests.mjs` | A non-package sample wrapper delegates to the Node facade, binds and refreshes opaque handles across package revisions, returns context windows, compiles exact localized edits, preserves accepted/rejected lifecycle and atomic rollback, and supports review resolution | LLM/provider latency or a production tool-server transport |
+| Batch compilation and recovery | `node tests/batch_source_binding_tests.mjs`, `node tests/error_recovery_contract_tests.mjs`, `node tests/capture_dependency_graph_tests.mjs` | Batch-start source identity survives structural index drift and savepoint restoration; true overlap and capture fan-out fail before mutation; recovery envelopes, retry bases, bounded CLI diagnostics, and complete-success exits remain stable | Whether a model follows the returned recovery action correctly |
+| Agent documentation contract | `node tests/agent_documentation_contract_tests.mjs` | The ordinary fast start stays within its 40–60 line/600-word budget, examples lead with scoped contextual extraction, and packaged skill-authoring guidance separates invariants, policies, transports, recovery, and presentation while the development wrapper stays outside package files | Whether a particular model reads or follows the instructions |
 | Agent edge cases | `node tests/canonical_paragraph_text_tests.mjs`, `node tests/document_inspection_edge_tests.mjs`, `node tests/docx_package_transaction_edge_tests.mjs`, `node tests/node_zip_archive_tests.mjs`, `node tests/agent_cli_edge_tests.mjs` | Revision-view semantics, cross-paragraph anchors, nested numbering, transaction reuse, multi-author cleanup, malformed ZIP handling, and destructive CLI safeguards | Desktop Word rendering and non-Windows CI |
 | Performance boundary regression | `node tests/performance_phase2_boundary_tests.mjs` | Stable facade re-exports, leaf imports, session rollback, isolated context commit, and comment-first scheduling | The Phase 1 one-parse/one-serialize performance target |
 | Live-session accuracy and instrumentation | `node tests/performance_phase1_session_tests.mjs` | One full parse/serialization, sequential semantic equivalence, exact accepted/rejected text, valid revisions, list/table/comment/highlight preservation, savepoint no-ops, and zero-serialization rollback | Desktop Word rendering |
@@ -79,6 +82,37 @@ not correctness gates. Per-operation DOM savepoints are retained because
 redline accuracy, no-op isolation, and rollback fidelity take precedence over
 the aspirational speed target.
 
+Run the observational agent-protocol benchmark with:
+
+```powershell
+npm run benchmark:agent
+```
+
+It writes `tmp/benchmarks/agent-workflow-latest.json` and compares canonical
+stateless Node, legacy file-based CLI, compact stdin/profile CLI, and the
+development-only session example. It records native/in-process CLI time, heap,
+serialized request bytes, protocol calls, instruction words/bytes, exact
+accepted/rejected text, comment preservation, ordering, recovery, and
+cross-author attribution. It does not measure or estimate LLM reasoning, exact
+tokens, tool transport, Claude, or OpenCode wall time; collect those separately
+in the calling harness. The checked WP-07 results are summarized in the
+[agent protocol rollout audit](validation-reports/2026-09-12-agent-protocol-rollout.md).
+
+Run the CLI discovery/output benchmark with:
+
+```powershell
+npm run benchmark:agent-cli
+```
+
+It records command-specific help size, broad inspect/search response size,
+context-window call count, pagination metadata, case-insensitive match parity,
+and native elapsed time in `tmp/benchmarks/agent-cli-discovery-latest.json`.
+The checked WP-00 through WP-02 before/after measurements are in the
+[agent CLI discovery baseline](validation-reports/2026-09-12-agent-cli-discovery-baseline.md).
+WP-03 through WP-05 profile, output-size, workflow, documentation, and package
+results are in the
+[agent CLI efficiency rollout audit](validation-reports/2026-09-13-agent-cli-efficiency-rollout.md).
+
 ## Cross-author revision slicing test suite
 
 The cross-author revision slicing subsystem introduces six complementary test lanes:

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

@@ -48,7 +48,11 @@
             "index": { "type": ["integer", "string"] }, "paragraphIndex": { "type": ["integer", "string"] },
             "paragraphId": { "type": "string" }, "occurrence": { "type": "integer", "minimum": 1 },
             "inTable": { "type": "boolean" }, "fingerprint": { "type": "string" }, "sourceFingerprint": { "type": "string" },
-            "revisionView": { "type": "string", "enum": ["accepted", "rejected"] },
+            "revisionView": {
+              "type": "string",
+              "enum": ["accepted", "rejected"],
+              "description": "Defaults to rejected for restore operations and accepted for other operation types."
+            },
             "captureRef": { "type": "string", "minLength": 1, "maxLength": 256 },
             "select": { "type": "string", "minLength": 1 }
           },

package/docs/validation-reports/2026-09-12-agent-cli-discovery-baseline.md

@@ -0,0 +1,56 @@
+# Agent CLI Discovery Baseline
+
+**Date:** 2026-09-12
+
+**Scope:** WP-00 baseline for command discovery, inspection breadth, contextual
+search, and compact mutation output
+
+## Before-state
+
+Measurements were captured from the source CLI immediately before WP-01/WP-02,
+using `tests/fixtures/sample_doc_test.docx` and pretty-printed CLI JSON:
+
+| Case | Result |
+|---|---:|
+| Global help | 171 bytes |
+| `apply --help` | 171 bytes; identical to global help |
+| `inspect --non-empty` | 72,387 bytes / 63 paragraphs |
+| Broad `extract --search "the"` | 13,968 bytes / 31 paragraphs |
+| Context retrieval | Search plus range: 2 commands |
+| Successful one-operation receipt | 464 bytes nested plus the same 464 bytes at root |
+
+The help payload did not describe command flags, search case behavior, or
+redline/comment/restore shapes. The detailed unscoped inspection exceeded the
+observed 64 KiB harness ceiling. Receipt deduplication is recorded here but is
+owned by WP-04, not WP-00 through WP-02.
+
+## WP-01/WP-02 result
+
+The checked post-change run produced:
+
+| Case | Result |
+|---|---:|
+| Global command-index help | 1,390 bytes |
+| Command-specific apply help | 4,400 bytes with flags and three operation shapes |
+| Bounded `inspect --non-empty` | 25,093 bytes / first 20 of 63 paragraphs |
+| Bounded `extract --search "the"` | 12,855 bytes / first 20 of 31 matches |
+| `extract --search "agreement" --around 2 --limit 1` | 2,178 bytes / one command / three paragraphs |
+
+Both formerly broad responses remain valid JSON below the 48 KiB soft limit and
+include stable continuation metadata. Search case variants returned identical
+indexes. A paragraph that individually exceeds the soft limit is returned whole
+and marked `oversizeItem` rather than truncating `exactText`.
+
+## Reproduction
+
+Run:
+
+```bash
+npm run benchmark:agent-cli
+```
+
+The benchmark retains the observed before-state constants and records the active
+post-change results in `tmp/benchmarks/agent-cli-discovery-latest.json`. It
+measures CLI response bytes, calls, paragraphs, selection metadata, and native
+elapsed time. It does not estimate model tokens, provider wall time, or tool
+transport latency.

package/docs/validation-reports/2026-09-12-agent-protocol-rollout.md

@@ -0,0 +1,86 @@
+# Agent Protocol Rollout Audit
+
+**Date:** 2026-09-12  
+**Scope:** WP-06 shell/documentation work and WP-07 repository-level rollout  
+**Benchmark:** `npm run benchmark:agent` on Node v24.11.1 / Windows x64,
+7 measured iterations after 2 warmups
+
+## Outcome
+
+The compact shell path removes the operations-file tool turn, and the
+development session example removes repeated target/policy payload. All measured
+paths produced the requested accepted view, restored the exact source text in
+the rejected view, passed package/revision validation, and preserved comment
+content. These are protocol and native-runtime measurements; no LLM/provider
+latency or token count was estimated.
+
+| Measure | Legacy | WP-06/07 result |
+|---|---:|---:|
+| Ordinary agent instructions | 2,023 words | 349 words (82.75% reduction) |
+| Repository launch card | 2,023 words | 527 words |
+| Shell workflow calls | extract + file write + apply (3) | extract + stdin apply (2; 33.33% reduction) |
+| Independent early-split permutations | one previously order-sensitive direction | both directions succeed |
+
+## Measured workflow results
+
+Median wall time includes the in-process CLI file/stdin transport for CLI rows.
+It does not include process startup, a model, provider tokenization, or tool
+transport.
+
+| Case | Legacy CLI | Compact stdin CLI | Session example | Session request bytes vs legacy |
+|---|---:|---:|---:|---:|
+| Terminal punctuation | 49.63 ms | 46.05 ms | 49.50 ms | 125 vs 255 (50.98% fewer) |
+| Term-duration phrase | 55.50 ms | 51.30 ms | 56.05 ms | 128 vs 630 (79.68% fewer) |
+| Simple mutuality | 62.82 ms | 50.22 ms | 58.45 ms | 281 vs 935 (69.95% fewer) |
+| Full-clause rewrite | 50.55 ms | 50.31 ms | 53.81 ms | 223 vs 407 (45.21% fewer) |
+| Comment + redline | 71.94 ms | 62.11 ms | 63.81 ms | 290 vs 724 (59.94% fewer) |
+
+Compared with the canonical stateless Node request envelope, localized session
+requests remained 86.11% smaller for punctuation, 89.96% smaller for a duration
+change, and 82.22% smaller for deterministic mutuality. A complete clause
+rewrite is naturally less compressible and is not presented as a localized-edit
+win.
+
+## Fidelity and recovery audit
+
+- The benchmark validates accepted and rejected paragraph text for every text
+  edit and verifies the mixed-batch comment definition remains present.
+- Both ten-edit permutations around an early paragraph split complete without
+  target errors.
+- An ambiguous target returns two candidates without auto-selection.
+- A stale session handle returns `STALE_TARGET_HANDLE` with recovery action
+  `reinspect`.
+- The default cross-author policy refuses the edit with `EXISTING_REVISIONS`.
+  `slice-cross-author` succeeds while retaining both original authors (Anson
+  Lai and John Doe), and rejecting the benchmark author's work still retains
+  those authors.
+- The CLI protocol regression proves UTF-8 stdin transport, package-revision
+  enforcement, source immutability, agent-profile defaults, atomic rollback,
+  progressive exit code 3, and rejected-view restoration.
+
+## Configuration decision
+
+> Historical note: this section records CLI contract version 5. Contract version
+> 7 decomposes `--profile agent`: it now supplies complete-success execution
+> without forcing atomic mode. Skills choose `--atomic` separately.
+
+No project or auto-discovered configuration file was added. The CLI already
+defaults author, strict targeting, validation, tracked changes, revision safety,
+and output naming. The explicit `--profile agent` flag reports
+`effectiveOptions`; hidden configuration discovery still would not justify its
+additional precedence reasoning.
+
+## Remaining external measurement
+
+Claude/OpenCode wall time, prompt tokens, generated tokens, and provider tool
+latency must be captured by those calling harnesses. The repository benchmark
+records bytes, words, calls, native time, failure behavior, and document
+fidelity so those external observations can be compared without conflating the
+library with model reasoning.
+
+## Automated verification
+
+- `npm test`: 107 passed, 0 failed.
+- `npm run check:types`: 123 runtime exports have declarations.
+- `npm run test:isolation`: core dependency and Word-API isolation passed.
+- Focused ESLint for all WP-06/07 source, benchmark, and test files passed.

package/docs/validation-reports/2026-09-13-agent-cli-efficiency-rollout.md

@@ -0,0 +1,86 @@
+# Agent CLI Efficiency Rollout Audit
+
+**Date:** 2026-09-13  
+**Scope:** WP-03 through WP-05 profile composition, compact mutation output,
+skill-authoring guidance, and package parity
+
+## Outcome
+
+CLI contract version 7 separates complete-success behavior from workflow
+policy. `--profile agent` now retains progressive execution and the ordinary
+`merge-same-author` policy; `--atomic` and explicit revision policies compose
+with it and appear in `effectiveOptions`. Reviewer precedence and the visible
+`AI Redliner` fallback are unchanged.
+
+Compact CLI mutation output now contains one authoritative top-level receipt per
+operation and no nested receipt copy. Successful exact-match diagnostics are
+omitted; successful space-equivalent matches retain `{ mode, differenceCount }`.
+Errors keep their bounded recovery evidence. The Node facade and standalone
+runner retain their complete per-result receipt and target-match structures.
+
+## Measured output
+
+`npm run benchmark:agent-cli` uses the same one-operation sample established in
+the WP-00 baseline:
+
+| Mutation response | Bytes | Change from pre-WP-04 |
+|---|---:|---:|
+| Pre-WP-04 pretty JSON | 2,968 | — |
+| Contract-7 pretty JSON | 2,216 | 25.34% smaller |
+| Contract-7 `--compact` JSON | 1,557 | 47.54% smaller |
+
+One-line serialization is 29.74% smaller than the structurally deduplicated
+pretty response, so contract version 7 exposes it explicitly through `--compact`
+and `compact-cli-json-v1`. It changes whitespace only.
+
+## Representative workflow audit
+
+The checked repository run records:
+
+- one relevant command-help lookup;
+- zero source, distribution-bundle, or ZIP-part inspection calls;
+- one contextual clause search and one apply attempt;
+- progressive agent-profile execution with complete-success exits;
+- exact accepted text and exact source restoration after rejection;
+- unchanged comment count and byte-identical source input; and
+- one top-level receipt with no nested copy.
+
+The existing agent workflow benchmark separately covers mixed comment/redline
+work, independent batch permutations, stale and ambiguous targeting recovery,
+and cross-author attribution. File-based and serializer-backed stdin operations
+are both exercised with the same Unicode payload by the CLI protocol suite.
+
+## Documentation and package parity
+
+The shipped documentation now includes `docs/SKILL_AUTHORING.md`. It separates
+safety invariants, workflow policy, transport choices, four-field recovery, and
+presentation rules. Executable documentation tests require each ordinary-use
+section to lead with focused contextual extraction and require skills to cite
+`humanReference`, provisions, or headings rather than machine paragraph
+ordinals.
+
+The npm allowlist includes the launch card, fast start, knowledge base,
+skill-authoring contract, schema, testing guide, and checked rollout reports.
+Development-only session examples and benchmark scripts remain excluded.
+
+The checked `npm pack --dry-run` contains 152 files (approximately 1.07 MB).
+It includes `node/cli-help.js`, the fast start, skill-authoring contract, and this
+audit; it excludes both agent benchmark scripts and the development session
+example.
+An unpacked tarball invocation reported contract version 7 and the same 16
+capabilities as the source CLI.
+
+## Automated verification
+
+- `npm test`: 110 passed, 0 failed.
+- `npm run check:types`: 123 runtime exports have declarations.
+- `npm run test:isolation`: dependency and Word-API isolation passed.
+- Focused ESLint for every WP-03 through WP-05 source, test, and benchmark file
+  passed.
+- `npm run build` and `npm pack --dry-run`: passed.
+
+## Measurement boundary
+
+These are native runtime, serialized-byte, command-count, and correctness
+measurements. They do not estimate Claude/OpenCode tokens, model reasoning time,
+provider transport latency, or end-to-end harness wall time.

package/engine/oxml-engine.js

@@ -28,7 +28,8 @@ import { applySurgicalMode } from './surgical-mode.js';
 import { applyReconstructionMode } from './reconstruction-mode.js';
 import { applyTableReconciliation, applyTextToTableTransformation } from './table-mode.js';
 import { getDefaultAuthor } from '../adapters/config.js';
-import { containsTrackedChanges, getTrackedChangeAuthors, withOoxmlSourceType } from '../core/word-xml.js';
+import { containsTrackedChanges, createWordElement, getTrackedChangeAuthors, withOoxmlSourceType } from '../core/word-xml.js';
+import { clonePropertiesWithoutRevisionHistory } from '../core/revision-cloning.js';
 import {
     NS_W,
     RevisionIdAllocator,
@@ -52,6 +53,62 @@ function getCommentIdsInOoxml(node) {
     }
     return [...ids].sort((a, b) => Number(a) - Number(b) || a.localeCompare(b));
 }
+
+function directWordChild(node, localName) {
+    return Array.from(node?.childNodes || []).find(child => (
+        child?.nodeType === 1
+        && child.namespaceURI === NS_W
+        && child.localName === localName
+    )) || null;
+}
+
+function insertedParagraphMarkMetadata(paragraph, author) {
+    const marker = directWordChild(directWordChild(directWordChild(paragraph, 'pPr'), 'rPr'), 'ins');
+    if (!marker) return null;
+    const markerAuthor = marker.getAttribute('w:author') || marker.getAttributeNS(NS_W, 'author') || '';
+    if (markerAuthor.trim().toLowerCase() !== String(author || '').trim().toLowerCase()) return null;
+    return {
+        id: marker.getAttribute('w:id') || marker.getAttributeNS(NS_W, 'id') || '',
+        author: markerAuthor,
+        date: marker.getAttribute('w:date') || marker.getAttributeNS(NS_W, 'date') || ''
+    };
+}
+
+function emptyParagraphBaseline(paragraph, serializer) {
+    const clone = paragraph.cloneNode(false);
+    const pPr = directWordChild(paragraph, 'pPr');
+    if (pPr) clone.appendChild(clonePropertiesWithoutRevisionHistory(pPr));
+    return serializer.serializeToString(clone);
+}
+
+function restoreInsertedParagraphMark(oxml, metadata) {
+    if (!metadata || typeof oxml !== 'string' || !oxml.trim()) return oxml;
+    const parsed = parseOoxmlSafe(oxml, 'text/xml');
+    if (!parsed.doc || parsed.error) return oxml;
+    const paragraph = parsed.doc.documentElement?.localName === 'p'
+        ? parsed.doc.documentElement
+        : getDocumentParagraphs(parsed.doc)[0];
+    if (!paragraph) return oxml;
+
+    let pPr = directWordChild(paragraph, 'pPr');
+    if (!pPr) {
+        pPr = createWordElement(parsed.doc, 'w:pPr');
+        paragraph.insertBefore(pPr, paragraph.firstChild);
+    }
+    let rPr = directWordChild(pPr, 'rPr');
+    if (!rPr) {
+        rPr = createWordElement(parsed.doc, 'w:rPr');
+        pPr.appendChild(rPr);
+    }
+    if (!directWordChild(rPr, 'ins')) {
+        const marker = createWordElement(parsed.doc, 'w:ins');
+        if (metadata.id) marker.setAttribute('w:id', metadata.id);
+        marker.setAttribute('w:author', metadata.author);
+        if (metadata.date) marker.setAttribute('w:date', metadata.date);
+        rPr.appendChild(marker);
+    }
+    return serializeXml(parsed.doc);
+}
 
 /**
  * Applies redline track changes to OOXML by modifying the DOM in-place.
@@ -77,11 +134,12 @@ export async function applyRedlineToOxml(oxml, originalText, modifiedText, optio
     const serializer = createSerializer();
     let parseWarnings = [];
     const operationWarnings = [];
-    let normalizedExistingRevisions = false;
+    let normalizedExistingRevisions = false;
+    let preservedInsertedParagraphMark = null;
     const existingRevisionsPolicy = options.existingRevisions || 'merge-same-author';
     const keepNormalizedNoOp = existingRevisionsPolicy === 'accept-all-first-keep-normalized';
-    const finalize = result => {
-        const withStatus = { ...result };
+    const finalize = result => {
+        const withStatus = { ...result };
         if (normalizedExistingRevisions && withStatus.hasChanges === false && withStatus.status !== 'error') {
             if (existingRevisionsPolicy === 'merge-same-author' || existingRevisionsPolicy === 'slice-cross-author') {
                 withStatus.oxml = workingOoxml;
@@ -105,10 +163,13 @@ export async function applyRedlineToOxml(oxml, originalText, modifiedText, optio
         if (warnings.length > 0) {
             withStatus.warnings = [...new Set(warnings)];
         }
-        if (!withStatus.status) {
-            withStatus.status = withStatus.hasChanges ? 'ok' : 'no-op';
-        }
-        return withOoxmlSourceType(withStatus);
+        if (!withStatus.status) {
+            withStatus.status = withStatus.hasChanges ? 'ok' : 'no-op';
+        }
+        if (preservedInsertedParagraphMark && withStatus.hasChanges && typeof withStatus.oxml === 'string') {
+            withStatus.oxml = restoreInsertedParagraphMark(withStatus.oxml, preservedInsertedParagraphMark);
+        }
+        return withOoxmlSourceType(withStatus);
     };
     const finalizeUnchanged = () => {
         if (normalizedExistingRevisions && keepNormalizedNoOp) {
@@ -181,9 +242,13 @@ export async function applyRedlineToOxml(oxml, originalText, modifiedText, optio
                     });
                 }
                 log('[OxmlEngine] Existing revisions from same author detected; rejecting previous changes to merge against baseline');
-                const rejected = rejectTrackedChangesInOoxml(inputOoxml, { author });
-                if (rejected.status === 'error') return finalize(rejected);
-                workingOoxml = rejected.oxml;
+                const soleParagraph = inputParagraphs.length === 1 ? inputParagraphs[0] : null;
+                preservedInsertedParagraphMark = insertedParagraphMarkMetadata(soleParagraph, author);
+                const rejected = rejectTrackedChangesInOoxml(inputOoxml, { author });
+                if (rejected.status === 'error') return finalize(rejected);
+                workingOoxml = preservedInsertedParagraphMark && !String(rejected.oxml || '').trim()
+                    ? emptyParagraphBaseline(soleParagraph, serializer)
+                    : rejected.oxml;
                 normalizedExistingRevisions = true;
                 const rejectedParsed = parseOoxmlSafe(workingOoxml, 'text/xml');
                 parseWarnings.push(...rejectedParsed.warnings);
@@ -230,8 +295,10 @@ export async function applyRedlineToOxml(oxml, originalText, modifiedText, optio
                     hasChanges: false,
                     status: 'error',
                     error: {
-                        code: 'EXISTING_REVISIONS',
-                        message: `Input OOXML contains tracked changes from another author (${authors.length ? authors.join(', ') : 'unattributed'}). Pass existingRevisions: "accept-all-first" or resolve revisions first.`
+                        code: 'EXISTING_REVISIONS',
+                        message: `Input OOXML contains tracked changes from another author (${authors.length ? authors.join(', ') : 'unattributed'}). Use existingRevisions: "slice-cross-author" for a surgical edit that preserves reviewer history; accepting or rejecting revisions requires separate authorization.`,
+                        revisionAuthors: authors,
+                        currentPolicy: existingRevisionsPolicy
                     }
                 });
             } else {

package/engine/run-builders.js

@@ -9,6 +9,7 @@ import { extractFormatFromRPr, RPR_SCHEMA_ORDER } from './rpr-helpers.js';
 import { createRevisionMetadata } from '../core/types.js';
 import { getFirstElementByTag } from '../core/xml-query.js';
 import { createWordElement } from '../core/word-xml.js';
+import { clonePropertiesWithoutRevisionHistory } from '../core/revision-cloning.js';
 
 /**
  * Creates an insertion/deletion wrapper.
@@ -319,14 +320,9 @@ export function snapshotAndAttachRPrChange(xmlDoc, rPr, author, dateStr, sourceN
     rPrChange.setAttribute('w:author', metadata.author);
     rPrChange.setAttribute('w:date', dateStr || metadata.date);
 
-    const previousRPr = createWordElement(xmlDoc, 'w:rPr');
     const source = sourceNode || rPr;
-
-    Array.from(source.childNodes).forEach(child => {
-        if (child.nodeName !== 'w:rPrChange') {
-            previousRPr.appendChild(child.cloneNode(true));
-        }
-    });
+    const previousRPr = clonePropertiesWithoutRevisionHistory(source)
+        || createWordElement(xmlDoc, 'w:rPr');
 
     rPrChange.appendChild(previousRPr);
 
@@ -369,14 +365,9 @@ export function snapshotAndAttachPPrChange(xmlDoc, pPr, author, dateStr, sourceN
     pPrChange.setAttribute('w:author', metadata.author);
     pPrChange.setAttribute('w:date', dateStr || metadata.date);
 
-    const previousPPr = createWordElement(xmlDoc, 'w:pPr');
     const source = sourceNode || pPr;
-
-    Array.from(source.childNodes).forEach(child => {
-        if (child.nodeType === 1 && child.nodeName !== 'w:pPrChange' && child.localName !== 'pPrChange') {
-            previousPPr.appendChild(child.cloneNode(true));
-        }
-    });
+    const previousPPr = clonePropertiesWithoutRevisionHistory(source)
+        || createWordElement(xmlDoc, 'w:pPr');
 
     pPrChange.appendChild(previousPPr);
 
@@ -390,4 +381,3 @@ export function snapshotAndAttachPPrChange(xmlDoc, pPr, author, dateStr, sourceN
     pPr.appendChild(pPrChange);
     return pPrChange;
 }
-