@ansonlai/docx-redline-js 0.8.4 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,212 @@
 # Changelog
 
+## 0.10.0
+
+### Added
+
+- **`existingRevisions: 'auto'`:** per target, `merge-same-author` when the target has no tracked changes or only the operation
+  author's, otherwise `slice-cross-author`. Unattributed changes count as another author's, and a `targetEnd` range resolves
+  over every paragraph in it. Accepted per operation, per batch, by `applyRedlineToOxml` and as `--existing-revisions auto`;
+  preflight reports the resolved policy. `resolveExistingRevisionsPolicy` is exported and accepts a node or an array of
+  paragraphs. CLI capability `existing-revisions-auto-v1`; the contract version stays 9.
+- **`compareDocumentInspections(expected, actual)`** (and `inspectionReviewShape`): compare two inspections by text, table position,
+  list label, review segments and comments, ignoring ids, dates and run boundaries. For verifying what a host committed.
+
+### Fixed
+
+- **Literal underscore runs are no longer Markdown emphasis:** `__x__` and `_x_` follow CommonMark flanking rules (not intraword,
+  not inside a longer underscore run, not around whitespace). Signature lines such as `_________________________` survive a
+  table reconciliation and a paragraph rewrite; `snake_case` stays literal.
+- **`structuredContent: false` is plain text:** a caller's plain-text `redline`/`replace` keeps inline Markdown markers literally
+  instead of turning them into formatting. Internal plain-structure calls are unchanged.
+- **Comment reply paraIds no longer collide with body paragraphs:** `applyCommentReplyToParts` (and the `comment_reply`
+  operation) now collects body `w14:paraId` values before allocating a reply's id. The scan's regex contained a literal
+  backspace instead of `\b`, so body ids were never seen.
+- **Internal:** the Reject All verifier's numbering check uses its memoized definition parser (it was never wired in), and the
+  reject-roundtrip matrix's revision-identity cross-check and `RECEIPT_RECONCILIATION_FAILED` gate now actually run (the
+  same backspace-for-`\b` defect had made them no-ops).
+- **Same-author checks count unattributed tracked changes as another author's:** a target holding the operation author's
+  revisions plus a change with no or a blank `w:author` passed as all same-author. `merge-same-author` then refused with
+  `UNSAFE_REVISION_NESTING` (`manual_resolution`) instead of `EXISTING_REVISIONS`, and `slice-cross-author` refused instead of
+  slicing; no revision was lost. Merge now refuses with `EXISTING_REVISIONS` (`revisionAuthors` lists named authors only; the
+  message adds `unattributed`), and slicing applies while Reject All still restores the unattributed change.
+
+## 0.9.0
+
+### Changed
+
+- **Unknown `paragraph-format.properties` keys are rejected:** `INVALID_OPERATION` with `field: properties.<key>`, `properties[]`
+  and `recovery.action: change_request`; nothing is applied. The 0.8.x `UNKNOWN_PARAGRAPH_FORMAT_PROPERTY` warning no longer fires.
+- **CLI contract version 9** (`list-format` operation type, capability `list-format-v1`). Integrations that do not send
+  `list-format` can keep requiring version 8.
+- **`UNSUPPORTED_LIST_CONVERSION` / `LIST_MARKER_NOT_BOUND` now point at `list-format`:** `recovery.action` is
+  `use_list_format_convert_plain` (was `apply_plain_text_or_convert_in_host`) and, when the original paragraph has no marker,
+  `recovery.suggestedOperation` carries the `list-format` request to send with the same target (for "Header" -> "C. Header":
+  `{ mode: 'convert-plain', format: 'upperLetter', strip: 'none', start: 3 }`). `listMarkers: 'literal'` is unchanged.
+- **`UNSUPPORTED_LIST_FORMAT_CHANGE` / `LIST_FORMAT_NOT_APPLIED` now point at `list-format` `change-format`:** `recovery.action`
+  is `use_list_format_change_format` (was `change_list_format_in_host`) and `recovery.suggestedOperation` carries
+  `{ type: 'list-format', list: { mode: 'change-format', format, level, scope: 'list' } }`; add a target on one item of the list.
+  `list-change` still never applies a format change itself.
+- **A `list-format` with `scope: 'list'` counts as a write to every item it rebinds:** another write to one of those items in the
+  same batch (`paragraph-format`, `highlight`, `format`, a second `list-format` of the same list) now fails before mutation with
+  `LIST_FORMAT_COMPOSITION_CONFLICT` (`reason: list-rebind`); in WP-5 it ran in batch order. Send it in a separate apply or use
+  `scope: 'range'`. A single-paragraph `redline` of an item still composes (see Added).
+- **Text-equal letter, roman and bullet header conversions are made in place:** a `redline` whose `modified` equals the plain
+  paragraph's typed-marker text (`B. Header` -> `B. Header`) now strips the marker as a tracked deletion and binds the list with a
+  tracked `w:pPrChange` in the same paragraph, like the decimal path. The previous whole-paragraph delete plus insert lost
+  `w14:paraId`, bookmarks and direct formatting and reviewed as a deleted and an inserted line; it remains only for shapes the
+  in-place conversion refuses. (It was reject-exact for plain runs but not for markers inside hyperlinks or smart tags, where the
+  Reject All verifier refuses it.)
+- **Operations that would break Reject All are refused by default:** the revision fidelity verifier now runs in
+  `enforce` mode. A refused operation leaves the document unchanged and returns `REVISION_FIDELITY_VIOLATION` with a
+  one-line message naming the invariant, the source paragraph (extraction index and excerpt), expected vs actual, an
+  explanation and a retry instruction; `violations[]`, `invariants` and `recovery.retryGuidance` carry the same detail for
+  agents, the message is also sent to `onWarn`, and compact CLI output keeps it. Opt out per call with
+  `verifyRevisionFidelity: 'warn'` (apply and warn) or `'off'` (diagnosis). CLI: `--revision-fidelity <enforce|warn|off>`,
+  shown in `effectiveOptions`; the agent profile rejects `off`. Capability `revision-fidelity-v1`. A single-target untracked
+  operation (`generateRedlines: false`) is also refused when it changes a paragraph outside its target in the Accept All or
+  Reject All view (invariant `ACCEPT_NEIGHBORS`).
+- **`ACCEPT_INTENT` and numbering-part existence in the revision fidelity check:** a tracked plain-text `redline` with complete
+  `modified` (no Markdown, list-marker or table syntax; single-paragraph targets and `targetEnd` ranges) is refused when Accept All of
+  its target would not read as `modified`. `REJECT_NUMBERING_REFS` also refuses a numId that the output binds or Reject All restores
+  (including inside `w:pPrChange`) when the source did not already use it and no `w:num` -> `w:abstractNum` -> `w:lvl` defines it in the
+  numbering available to the operation. Accept-first range targets now use the exact accepted scope.
+- **`ensureNumberingArtifactsInZip` always merges numbering, and refuses id conflicts:** the optional `mergeNumberingXml`
+  callback is ignored (the single merge is `mergeNumberingParts` in `services/numbering-allocation.js`), an existing
+  `numbering.xml` is no longer replaced when no callback is given, and an incoming `w:abstractNum` / `w:num` whose id exists with
+  different content throws `NUMBERING_ID_CONFLICT` instead of silently binding new paragraphs to another list. `openDocx` also
+  rejects output that introduces a dangling `numId`, `abstractNumId` or `ilvl` (`NUMBERING_*` issues).
+- **Receipt kinds:** a whole paragraph deleted by an empty `modified` reports its deleted paragraph mark with receipt kind `del`
+  (was `structural`); the explicit `1. Header` list conversion now receipts its `w:pPrChange`.
+- **`paragraph-format` keeps the earliest same-author `w:pPrChange` snapshot** and refuses to overwrite another author's pending
+  snapshot (`PARAGRAPH_FORMAT_REVISION_CONFLICT`); see Added.
+
+### Added
+
+- **`redline` + `list-format` on one paragraph in one batch:** a changed-text header (`1. Old` -> `1. New`) is a `redline` that keeps
+  the typed marker exactly (`modified: '1. New'` or `replacements`) plus a `list-format` `convert-plain` of the same paragraph. The
+  batch compiler allows exactly this pair (both bind at batch start) and fixes the order whatever the batch order: the redline runs
+  first, then the list-format strips the unchanged marker, so Accept All shows label `1.` with `New` and Reject All the literal
+  `1. Old` (verified in Word with `ListFormat.ListString`, including a `3.` start value). A single-paragraph `redline` of a list item
+  also composes with a `change-format`/`join` that rebinds it. Incompatible pairs are refused before mutation with
+  `LIST_FORMAT_COMPOSITION_CONFLICT` (`reason`: `marker-changed` with `sourceMarker`/`modifiedMarker`, `redline-unchanged`,
+  `redline-shape`; `recovery.action: split_text_and_list_changes`); other kinds keep `OVERLAPPING_SOURCE_TARGETS` /
+  `REVISION_ORDER_CONFLICT`. No new capability: it is part of `list-format-v1` behavior.
+- **`list-format` `change-format` and `join` modes (`list-format-change-v1`, contract version stays 9):** `change-format` changes
+  the kind or numbering format of an existing list (`format`, `lvlText`, `start`, `level`, default the target's level). It never
+  edits the shared definition: a NEW `w:abstractNum` + `w:num` is allocated with the source levels, indentation and fonts copied
+  and one level redefined (`w:isLgl`, picture bullets and a bullet's symbol font are dropped on a format change), and each item is
+  rebound with a tracked `w:pPrChange`, so Reject All restores the original labels and Accept All shows the new ones (verified in
+  Word with `ListFormat.ListString` after `Revisions.AcceptAll()`/`RejectAll()`: bullets to `1.`, `1.` to `A.`, a nested level to
+  `(i)`, and two range splits). `scope: 'list'` (default) rebinds every live item of the list (`items[].inTarget` marks those outside
+  the target); `scope: 'range'` rebinds a `target`..`targetEnd` range that runs to the end of the list and continues its count
+  (start values on the new definition, including a split that starts at a nested item). `join` binds the target list (or a range
+  running to its end) to the `numId` of `list.continueFrom`, an item of an earlier list, so it continues that count; `continueFrom` is
+  bound at batch start. Tracked-deleted paragraphs keep their `w:numPr`; a same-author earlier `w:pPrChange` snapshot is kept;
+  later operations in a batch see definitions earlier ones allocated. Refused before any write: `LIST_FORMAT_TARGET_NOT_LIST`,
+  `LIST_FORMAT_MIXED_RANGE` (plain paragraphs, several lists, or several levels without `list.level`), `LIST_FORMAT_STYLE_LINKED`
+  (heading/list-style numbering), `LIST_FORMAT_STYLE_NUMBERED`, `LIST_FORMAT_SPLIT_UNSUPPORTED` (`mid-sequence` range,
+  `nested-restart`, `shared-definition` abstract used by another list, `interleaved` join), `LIST_FORMAT_DEFINITION_UNSUPPORTED`
+  (missing definition, `w:lvlOverride/w:lvl`, `w:lvlRestart` in a split), `LIST_FORMAT_JOIN_INVALID` and
+  `PARAGRAPH_FORMAT_REVISION_CONFLICT`; an untracked rebinding outside the target is refused; a no-op is `ok` with a
+  `LIST_FORMAT_UNCHANGED` warning. Results carry `list` (`sourceNumId`, `numId`, `items[]`, `levelStarts` or `continueFrom`).
+  An older CLI refuses the new modes with `INVALID_OPERATION` (`field: list.mode`), so negotiate the capability.
+- **`list-format` operation, `convert-plain` mode (`list-format-v1`):** binds plain paragraphs (a target, or `target`..`targetEnd`
+  in one container) whose text starts with a typed marker (`1.`/`1)`, `A.`/`a)`, `IV.`/`iv.`, `-`/`•`) to a NEW list definition in
+  place. The marker is removed with a tracked `w:del` of exactly the marker text (`strip: 'marker'`, default) and the `w:numPr`
+  binding is a tracked `w:pPrChange`, so Reject All restores the literal marker and the unnumbered paragraph and Accept All shows
+  the list label (verified in Word: `ListFormat.ListString` after `Revisions.AcceptAll()`/`RejectAll()` for `A.`, `1.`, `I.` and a
+  `C.` start value). Each marker's value is the item's value (`startOverride` on the new `w:num`; the label keeps the typed `.`/`)`);
+  consecutive values share one list, a gap starts a new list at the typed value, body paragraphs in the range stay plain, and a
+  later `list-format` in the same batch whose first value continues the previous list joins it. `strip: 'none'` with `format`
+  (and optional `start`) binds without touching the text. Ambiguous or unsupported shapes are refused with recovery envelopes:
+  `LIST_MARKER_NOT_FOUND`, `LIST_MARKER_AMBIGUOUS` (a lone `I.`/`C.` reads as letter or roman; set `list.format`),
+  `LIST_MARKER_UNSUPPORTED` (mixed markers, `2.1.`, `(a)`, a marker inside a hyperlink/field/revision, format mismatch),
+  `LIST_FORMAT_TARGET_IS_LIST`, `LIST_FORMAT_STYLE_NUMBERED` (style-linked numbering; needs `stylesXml` on the bare runner, read from
+  the package by `openDocx`) and `PARAGRAPH_FORMAT_REVISION_CONFLICT`. Body only. Results carry `list` (`format`, `items[]` with
+  `numId`/`value`, `skipped[]`). Schema `$defs.listFormat`, `ListFormatDocumentOperation` in `index.d.ts`.
+- **`paragraph-format.numbering` binding (`paragraph-numbering-binding-v1`, no contract bump):** `properties.numbering` is
+  `{ numId, level? }` (bind the paragraph to an existing list) or `null` (remove its direct list binding), recorded as a tracked
+  `w:pPrChange` so Reject All restores the previous `w:numPr` exactly and Accept All shows the new one (verified in Word with
+  `Document.Revisions.RejectAll()/AcceptAll()` and `ListFormat.ListString`). `w:numPr` is inserted at its CT_PPr position
+  (after `widowControl`, before `suppressLineNumbers`/`spacing`/`ind`; `ilvl` before `numId`). A binding never allocates: an unknown
+  `numId` or undefined level is refused `PARAGRAPH_NUMBERING_NOT_FOUND`. `paragraph-format` now keeps the earliest `w:pPrChange`
+  snapshot for repeated same-author edits (it used to replace it, so Reject All restored the intermediate state) and refuses to
+  overwrite another author's pending snapshot (`PARAGRAPH_FORMAT_REVISION_CONFLICT`). Letter and roman literal-marker headers
+  (`C.`, `iv.`) now convert with their start value instead of restarting at the first item.
+- **List conversion diagnostics (`list-conversion-diagnostics-v1`, no contract bump):** text edits no longer report a silent `ok`
+  when they cannot create list structure. A plain paragraph whose new text starts a list marker returns the warning
+  `LIST_MARKER_NOT_BOUND` (`diagnostics[]` on the operation result, `CODE: message` in `warnings`), or `UNSUPPORTED_LIST_CONVERSION`
+  under the strict policy (`--profile agent`, `--atomic`, or `strictListConversion: true`). A list item whose retained marker asks for a
+  different kind or format than its numbering definition returns `LIST_FORMAT_NOT_APPLIED` / `UNSUPPORTED_LIST_FORMAT_CHANGE`.
+  `listMarkers: 'literal'` on an operation opts out. `paragraph-format.properties` is now a closed schema; unknown keys (such as
+  `spacingAfter`) first produced an `UNKNOWN_PARAGRAPH_FORMAT_PROPERTY` warning (superseded in 0.9.0, see Changed).
+  Independent of `REVISION_FIDELITY_VIOLATION`; compact CLI output keeps `diagnostics` and the error fields.
+
+- **Numbering allocator:** new `services/numbering-allocation.js` (exported from the package root): `allocateNumberingDefinition`
+  (new abstractNum + num with fresh ids, copied level geometry, per-level `startOverride`), `allocateNumberingForReplacement`
+  (same-kind source-list continuation or fresh allocation; tracked-deleted source paragraphs never change `numPr`),
+  `mergeNumberingParts` / `mergeNumberingXmlBySchemaOrder` (now with an `onConflict` option), `canonicalNumberingDefinition` and
+  `validateNumberingIntegrity`. The standalone runner's consumers and the `openDocx` facade merge through the same function;
+  `reuseSourceListNumbering` is replaced by allocator policy.
+- **Revision fidelity verifier:** every tracked operation now checks, on the live DOM and without extra
+  serialization, that Word's Reject All of its output equals Word's Reject All of the source (paragraph count and order,
+  canonical text including breaks and tabs, paragraph properties, `numPr`, hyperlink/field/content-control membership).
+  A mismatch refuses the operation (see Changed); in `warn` mode it is applied with the message in `warnings` and
+  `revisionFidelityViolations`. The Word-semantics simulator is `core/word-revision-semantics.js`, validated against
+  recorded Word 16 Reject All / Accept All results (`tests/fixtures/word-revision-semantics/expectations.json`).
+
+- **`UNTRACKED_CREATED_REVISION` invariant:** an operation with `generateRedlines: false` is refused (default `enforce`) when its
+  output contains a revision id (`w:ins`, `w:del`, moves, `*PrChange`, paragraph-mark and row revisions) that the source did not
+  have. A foreign revision sliced around the edit keeps its element, author and date and is not counted. It reports as
+  `REVISION_FIDELITY_VIOLATION` with `violations[].invariant: 'UNTRACKED_CREATED_REVISION'`, also for range targets.
+
+### Internal
+
+- **Revision fidelity verifier cost cut from about +39% to about +8% per batch:** each verified operation's projections (accepted and rejected views, revision-id signatures, numbering references) are reused as the next operation's baseline, numbering definitions are parsed once per part, and the revision-view projection no longer builds live node lists. No check was weakened.
+- **One paragraph-mark revision helper:** `engine/paragraph-mark-revisions.js` is now the only module that constructs a tracked paragraph mark (`w:ins`/`w:del` under `w:pPr/w:rPr`): `markParagraphInserted`, `markParagraphDeleted`, `setParagraphPropertiesMarkRevision`, `restoreParagraphMarkInserted`, string builders `paragraphMarkRevisionXml` / `paragraphMarkPPrXml`, and `planParagraphMarks` (asserts the Reject All paragraph-count invariants). Document-level shortcuts, list generation, reconstruction, text-to-table and generated tables use it, and `tests/paragraph_mark_single_site_tests.mjs` fails on any other construction site. Output is unchanged except that a new mark `rPr` is placed before `sectPr`/`pPrChange`, an existing mark is replaced rather than duplicated, and the empty-modified shortcut's deleted-mark receipt kind is `del` (was `structural`).
+
+### Fixed
+
+- **A `targetEnd` given as a compact handle (`paragraphId` + `fingerprint`, no numeric `index`) was silently ignored** for a
+  plain `redline`, so only the first paragraph of the range was replaced and the rest stayed in the accepted text. The range is now
+  resolved from the end handle; a range that crosses a table or other container boundary is refused `TARGET_RANGE_INVALID`.
+- **Range replace over empty paragraphs no longer fails receipt reconciliation:** a replacement whose diff deletes only paragraph
+  breaks recorded a paired deletion revision id in the receipt that was never written, so the operation was refused with
+  `RECEIPT_RECONCILIATION_FAILED`. Paired replacement ids are now recorded only when written. The reject-roundtrip matrix
+  treats that code as a failure, not a skipped refusal.
+- **Plain `redline` keeps `w14:paraId` / `w14:textId`:** reconstruction used to rebuild the paragraph without its identity 
+  attributes; the rebuilt paragraph that survives for a source paragraph (not tracked-deleted) now keeps them, once (an inserted
+  split gives them to the paragraph whose mark Reject All keeps). A composed `redline` + `list-format` pair keeps identity.
+- **Text-changed header conversion with direct `keepNext` / spacing is no longer refused `REJECT_PARAGRAPH_PROPS`:** the list
+  fallback's tracked-deleted source paragraph keeps its original `pPr`; the new list paragraph carries the direct properties and
+  the source `w14:paraId`.
+- **`ReconciliationPipeline.executeTableGeneration` inserts a tracked table block:** the public pipeline method generated
+  tracked cell text in untracked rows (the defect `engine/table-mode.js` had); rows now carry `w:trPr/w:ins` so Reject All
+  removes the table.
+- **Separate list conversions in one batch continue one list:** two `redline` operations that turned non-adjacent headers into continuing markers (`A. Header`, `B. Header`) each allocated their own numbering instance, so Word showed `A.`, `B.` (start values) but as two lists, and a later item inserted between them would not renumber. The structural list fallback now uses the batch sequence state `list-format convert-plain` uses: same kind, format and level with a continuing value reuses the previous operation's live `numId` (a `redline` and a `convert-plain` of the same format join one list too); a gap (`A.` then `C.`) or a different format allocates a new instance. Ids still come from `services/numbering-allocation.js`. (Reported against 0.8.4.)
+- **Weak-target localized replacements no longer delete soft-break paragraphs:** a `replacements` edit targeted only by `index` + `exactText` (no `paragraphId`/`fingerprint`) in a paragraph containing `<w:br/>` returned `ok` but tracked the whole paragraph as deleted and inserted nothing, because the batch compiler treated the line break in `exactText` as a multi-paragraph target and skipped replacement compilation. Localized replacements now always bind at batch start, so weak and strong targets behave identically. Every localized replacement also has its accepted result checked against the compiled text before commit (`PATCH_ROUNDTRIP_MISMATCH`, nothing applied), and uncompiled replacements are refused rather than applied.
+- **Reconstruction keeps wrappers and deleted placeholders:** a text edit in a paragraph with a `w:fldSimple` no longer drops the field (Reject All lost its result text); a deleted manual break, tab or inline object is a tracked deletion instead of disappearing; and converting a paragraph to a list keeps hyperlink and content-control containers around the deleted runs, so Reject All keeps the text inside its link. Found by the reject-roundtrip matrix.
+- **Punctuation edits stay surgical:** leading and trailing punctuation are separate diff tokens and unchanged substantive words anchor the re-diff, so "agents and attorneys" -> "agents, attorneys, accountants and other professional advisors" marks only " and" -> "," and the appended items.
+- **Table reconciliation keeps untouched cell paragraphs:** editing one cell of a Markdown table reconciliation collapsed a multi-paragraph cell (for example `LS` plus a trailing empty paragraph) to one paragraph, untracked, so Reject All lost a paragraph. Cells whose only difference is trailing empty paragraphs are now unchanged, and a modified multi-paragraph cell is reconciled paragraph by paragraph (inserted paragraphs carry tracked marks).
+- **Text-to-table redlines insert tracked table rows:** a paragraph range converted to a Markdown table carried tracked cell text but untracked rows, so Reject All left an empty table behind. Rows now carry `w:trPr/w:ins` and tracked cell paragraph marks like other inserted tables.
+- **Explicit-start list conversion is reversible with Reject All:** converting a `1. Header` paragraph to a list bound `numPr` without recording a `w:pPrChange`, so rejecting the tracked deletion of the marker left a numbered item. The binding now records the original paragraph properties (empty `<w:pPr/>` when none) in a receipted `w:pPrChange`.
+- **Reject/Accept All match Word for table cells and `pPrChange`:** rejecting an inserted paragraph mark keeps the cell's last paragraph (empty) instead of dropping it, accepting a fully deleted sole-paragraph table removes the table, and rejecting a `pPrChange` keeps the paragraph-mark `rPr` and `sectPr` instead of discarding them.
+- **Property readers ignore `pPrChange`/`rPrChange` snapshots:** a new `core/current-properties.js` accessor reads only direct `w:pPr`/`w:rPr` children, so a tracked property change no longer makes its historical `numPr`, `pStyle`, `outlineLvl` or `b`/`i` look current. Markdown export, numbering-context detection, list-numbering reuse/overwrite, list-shape checks and captured-entity kind now use it; a usage test fails on new descendant property lookups.
+- **Explicit `1. Header` list conversion works on a bare `document.xml`:** with no numbering part the batch had no numbering id state, so the conversion aborted after recording tracked deletions in the receipt and failed with `RECEIPT_RECONCILIATION_FAILED`. The bare runner now always seeds numbering ids as `openDocx` does, and an aborted conversion no longer records receipt revisions.
+- **`generateRedlines: false` stays untracked under `slice-cross-author`:** the surgical insert computed its nested-revision flag as
+  `!(generateRedlines && ...)`, which is true whenever `generateRedlines` is false, so an inserted word was wrapped in a new tracked
+  `w:ins` (`applyRedlineToOxml` and `applyOperationsToDocumentXml`; `redline`/`replace`, `modified`/`replacements`). It now writes
+  plain runs, like `merge-same-author`, and leaves other authors' revisions intact (a foreign insertion is sliced around the edit).
+- **Table appended after the final paragraph of a pretty-printed document keeps its tracked trailing paragraph:** a whitespace
+  text node between the last paragraph and `w:sectPr` made the retained-paragraph table append believe the table did not end
+  the body, so the body ended with a table and Word added an untracked empty paragraph that Reject All left behind (plugin
+  report R5; Word differential 5 vs 4 paragraphs). The append now skips non-element nodes when deciding. The Word-semantics
+  simulator (and therefore the post-apply verifier) counts the untracked paragraph Word supplies after a body-final table, so
+  the old output is refused with `REVISION_FIDELITY_VIOLATION`. Documents without whitespace between blocks (the plugin's
+  own) were already correct on `Revisions.RejectAll()` and the ribbon; `Document.RejectAllRevisions()` still leaves the
+  tracked-inserted last mark behind (a Word API quirk, see the fidelity plan).
+
 ## 0.8.4
 
 ### Added
@@ -71,7 +278,7 @@
 ### Known limitations
 
 - Plain paragraph to list conversion and list format changes are not yet supported canonically; see
-  `docs/plans/2026-09-30-canonical-list-operations.md`.
+  `docs/plans/completed/2026-09-30-canonical-list-operations.md`.
 - `1. Header` to `1. Header` on a bare `document.xml` (not a packaged `.docx`) can fail with `RECEIPT_RECONCILIATION_FAILED`.
 
 ## 0.8.2

package/README.md

@@ -15,14 +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
+- Reject All verification: every tracked operation is refused unless Word's Reject All of the output reproduces the source
 - Status/error result fields for parse, targeting, and existing-revision failures
 - Localized exact replacements against inspected targets, plus optional fail-closed speculative CLI edits
 - 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.8.x
+## What's New in 0.10.0, 0.9.0 and 0.8.x
 
-The current release is 0.8.4. The CLI contract remains version 8 throughout the 0.8 line.
+0.10.0 adds `existingRevisions: 'auto'` (capability `existing-revisions-auto-v1`, contract version stays 9), which
+merges a target's own-author history and slices around another reviewer's, per target. It also adds
+`compareDocumentInspections` for checking a committed document against a prepared one, and fixes underscore runs such as
+signature lines (`_____`) collapsing to one `_`. A caller's `structuredContent: false` now keeps inline Markdown markers
+literal. See the [0.10.0 release notes](./docs/releases/0.10.0.md).
+
+0.9.0 moves the CLI contract to version 9 and adds the `list-format` operation (`convert-plain`, `change-format`, `join`),
+`paragraph-format` numbering binding, list-conversion diagnostics, a single numbering allocator and merge, and a Reject All
+revision fidelity verifier that refuses by default (`REVISION_FIDELITY_VIOLATION`). See the
+[0.9.0 release notes](./docs/releases/0.9.0.md) and the [CHANGELOG](./CHANGELOG.md). The CLI contract was version 8
+throughout the 0.8 line.
 
 - **0.8.0, universal document facade:** `openDocx` and `DocxDocument` are exported from the primary entry point and work
   on `Uint8Array` input in any JavaScript runtime. ZIP handling uses `fflate` and SHA-256 is pure JavaScript, so there are no
@@ -287,7 +298,7 @@ docx-redline preflight contract.docx --operations operations.json --author "Edit
 All commands emit JSON on stdout. `apply` defaults:
 - **Author**: Defaults to `'AI Redliner'` (or `DOCX_REDLINE_AUTHOR` environment variable).
 - **Output overwrite**: Destination files provided via `--output` overwrite by default. Pass `--no-overwrite` or `--no-clobber` to safeguard existing destination files. The source input is never overwritten unless `--in-place` is specified.
-- **Existing revisions**: Defaults to `'merge-same-author'`. Pass `--existing-revisions slice-cross-author` to edit inside another reviewer's pending insertions with native carrier slicing.
+- **Existing revisions**: Defaults to `'merge-same-author'`. Pass `--existing-revisions slice-cross-author` to edit inside another reviewer's pending insertions with native carrier slicing, or `--existing-revisions auto` to choose per target (slicing only where another reviewer's changes are present).
 - **Transactionality**: Defaults to `atomic: false` (applies valid operations and reports any failures). Pass `--atomic` for all-or-nothing rollback on any operation error.
 - **Complete-success exit**: Pass `--require-complete` when a progressive `partial` result must exit with code `3`; errors exit with code `2`. Without the flag, partial results retain the legacy zero exit code, so always inspect `completion`.
 - **Agent profile**: `--profile agent` enables complete-success exit behavior while retaining the ordinary progressive transaction and existing-revision defaults. Compose it with `--atomic` or an explicit `--existing-revisions` policy when intended, and verify the resolved `effectiveOptions`.
@@ -311,7 +322,9 @@ 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 8 and the additive
+`docx-redline version` reports contract version 9 (adds the `list-format` operation type). Contract 9 adds the
+capabilities `revision-fidelity-v1`, `list-conversion-diagnostics-v1`, `paragraph-numbering-binding-v1`,
+`list-format-v1` (`convert-plain`) and `list-format-change-v1` (`change-format` and `join`), alongside 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`,
@@ -320,7 +333,10 @@ user-facing Word locations; use `humanReference`, `provision`, or
 `speculative-search-apply-v1`, `localized-change-summary-v1`, and
 `restore-shortcuts-v1`, plus `localized-space-equivalence-v1` capabilities. Header/footer
 `part` targeting, the `comment_resolve` operation and `delete-comments --comment-id` are advertised as
-`header-footer-parts-v1`, `comment-resolve-operation-v1` and `delete-comments-by-id-v1`.
+`header-footer-parts-v1`, `comment-resolve-operation-v1` and `delete-comments-by-id-v1`. The remaining advertised
+capabilities are `atomic-batch-results-on-package-failure`, `baseline-aware-validation`, `compact-mutation-results`,
+`cross-author-revision-slicing`, `document-scoped-list-revision-ids` and `format-text-occurrence-v1`. 0.10.0 adds
+`existing-revisions-auto-v1` (`existingRevisions: 'auto'`) without a contract bump.
 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.
@@ -366,11 +382,14 @@ See the [compact agent fast start](./docs/AGENT_FAST_START.md), the
 | `generateRedlines` | `boolean` | `true` | When `true`, emit Word-native tracked changes (`w:ins`/`w:del`). When `false`, apply clean direct edits without revision markup. **Note: Redlines are not always the preferred method** — pass `generateRedlines: false` (or `--no-redlines` via CLI) when producing clean execution drafts, restructuring documents, or when revision clutter is unwanted. |
 | `author` | `string` | `'AI Redliner'` | Reviewer/author name stamped on generated tracked changes and comments. Overridable via `DOCX_REDLINE_AUTHOR` env variable. |
 | `atomic` | `boolean` | `false` | Batch transaction mode. By default (`false`), valid edits are applied and failing operations report errors. When `true`, any operation failure rolls back the entire batch to the original document state (`rolledBack: true`, `hasChanges: false`). Feature prominently in high-assurance workflows. |
-| `structuredContent` | `boolean` | `true` | Auto-detects Markdown tables, headings (`#`), and lists in replacement text and renders them as native Word elements (`w:tbl`, `w:pStyle`, `w:numPr`). Pass `false` to treat replacement text strictly as plain text. |
+| `structuredContent` | `boolean` | `true` | Auto-detects Markdown tables, headings (`#`), and lists in replacement text and renders them as native Word elements (`w:tbl`, `w:pStyle`, `w:numPr`). Pass `false` to treat replacement text strictly as plain text: inline Markdown markers (`**`, `__`, `_`, `~~`, `++`) are kept literally. With `true`, underscores follow CommonMark flanking rules, so signature lines (`_____`) and `snake_case` stay literal. |
 | `pairReplacements` | `boolean` | `true` | Links adjacent `<w:del>` and `<w:ins>` revisions with matching timestamps so Word groups them as a single replacement in the Reviewing Pane. |
 | `strictTargets` | `boolean` | `true` (CLI/facade) | Requires exact target descriptors (`exactText`, `paragraphId`, `index`, `occurrence`, `fingerprint`) and forbids ambiguous matching. Defaults to `false` in low-level runner for backwards compatibility. |
-| `existingRevisions` | `string` | `'merge-same-author'` | How to handle paragraphs with existing tracked changes. `'merge-same-author'` merges revisions from the same author and protects other authors with `EXISTING_REVISIONS`. `'slice-cross-author'` keeps that same-author merge behavior while allowing Word-native edits inside another author's pending insertion. Pass `'accept-all-first'` to normalize prior revisions or `'reject-input'` to refuse editing revised paragraphs. |
+| `existingRevisions` | `string` | `'merge-same-author'` | How to handle paragraphs with existing tracked changes. `'merge-same-author'` merges revisions from the same author and protects other authors with `EXISTING_REVISIONS`. `'slice-cross-author'` keeps that same-author merge behavior while allowing Word-native edits inside another author's pending insertion. Pass `'accept-all-first'` to normalize prior revisions or `'reject-input'` to refuse editing revised paragraphs. `'auto'` chooses per target: `'merge-same-author'` when the target has no tracked changes or only the operation author's, otherwise `'slice-cross-author'` (preflight reports the resolved policy). |
 | `removeFormatting` | `boolean` | `false` | When `true` and the text is unchanged with no Markdown hints, strips existing bold/italic/underline/strikethrough formatting. |
+| `verifyRevisionFidelity` | `'enforce' \| 'warn' \| 'off'` | `'enforce'` | Post-apply Reject All check described under [Reject All verification](#reject-all-verification). CLI: `--revision-fidelity`; the agent profile rejects `off`. |
+| `listMarkers` | `'literal'` | unset | Per operation. Accepts list-marker text as literal text and suppresses `LIST_MARKER_NOT_BOUND`, `UNSUPPORTED_LIST_CONVERSION`, `LIST_FORMAT_NOT_APPLIED` and `UNSUPPORTED_LIST_FORMAT_CHANGE` for that operation. |
+| `strictListConversion` | `boolean` | `atomic` | Makes `UNSUPPORTED_LIST_CONVERSION` and `UNSUPPORTED_LIST_FORMAT_CHANGE` errors instead of warnings (capability `list-conversion-diagnostics-v1`). The CLI agent profile and `--atomic` set it; an operation's `listMarkers: 'literal'` wins. |
 | `sanitizeInput` | `boolean` | `false` | Opt-in removal of standalone leading assistant-preface lines. Literal dollar signs and `\n` sequences are always preserved. |
 
 Same-author revision merging refuses paragraphs containing comment anchors with
@@ -410,6 +429,19 @@ The engine applies Microsoft Word Desktop-native tracked change structures:
 - **Straddle deletions**: Deletions spanning between baseline text and pending insertions cleanly partition across their respective container contexts without invalid coalescing.
 - **Lifecycle parity**: Accepting or rejecting either reviewer independently produces identical results to Microsoft Word Desktop's native review pane.
 
+### Comparing inspections
+
+`compareDocumentInspections(expected, actual)` checks that two inspections describe the same reviewable document. It compares paragraph text, table position, list labels, review segments (adjacent segments of one kind and author are merged) and comments, and ignores ids, dates, rsids, paragraph ids and run boundaries. A host that writes a prepared package through another API can inspect what it prepared and what it committed, then compare them:
+
+```js
+import { inspectDocumentParts, compareDocumentInspections } from '@ansonlai/docx-redline-js';
+
+const check = compareDocumentInspections(inspectDocumentParts(preparedParts), inspectDocumentParts(committedParts));
+if (!check.matches) console.warn(check.differences); // at most the first 10 differences
+```
+
+`inspectionReviewShape(inspection)` returns the normalized shape the comparison uses.
+
 ### Replacing a heading with a tracked list
 
 The list route treats a one-paragraph heading expanded into multiple markdown
@@ -437,6 +469,58 @@ for it. For a complete `word/document.xml`, prefer
 `applyOperationToDocumentXml(...)` so replacement nodes and numbering artifacts
 are imported at the correct scope.
 
+### List operations (`list-format`)
+
+Text edits never create or restyle list structure. Typed markers such as `1.` or `A.` stay literal text, and a
+`list-change` that retypes markers keeps the old numbering (it warns `LIST_FORMAT_NOT_APPLIED`, or fails
+`UNSUPPORTED_LIST_FORMAT_CHANGE` under the strict policy, with a `list-format` request in `recovery.suggestedOperation`).
+Structure changes use the `list-format` operation. Every mode records each paragraph's previous `w:numPr` in a tracked
+`w:pPrChange`, so Reject All restores the original labels exactly and Accept All shows the new ones. The shared numbering
+definitions in `numbering.xml` are never edited in place: new definitions come from one allocator and are merged by one numbering
+merge, and an id that already exists with different content fails with `NUMBERING_ID_CONFLICT`. `paragraph-format`
+`properties.numbering` binds or removes a list on a paragraph the same way (tracked `w:pPrChange`). Unknown
+`paragraph-format.properties` keys are rejected with `INVALID_OPERATION`. The CLI advertises `list-format-v1` (contract version 9) for
+`convert-plain` and `list-format-change-v1` for `change-format` and `join`.
+
+```js
+const doc = openDocx(bytes);
+const result = await doc.applyOperations([
+  // Typed headers "A. Scope" .. "C. Fees" become a real A./B./C. list. Each marker is a tracked deletion, and body
+  // paragraphs in the range stay plain. A typed start value ("C.") is kept.
+  { type: 'list-format', target: { exactText: 'A. Scope' }, targetEnd: { exactText: 'C. Fees' },
+    list: { mode: 'convert-plain' } },
+  // Bullets become 1., 2., 3. A new definition copies the list's levels and indentation.
+  { type: 'list-format', target: { exactText: 'Photo identification' },
+    list: { mode: 'change-format', format: 'decimal' } },
+  // A later list continues an earlier one (1. 2. / 1. 2. becomes 1. 2. / 3. 4.).
+  { type: 'list-format', target: { exactText: 'Confidentiality' },
+    list: { mode: 'join', continueFrom: { exactText: 'Termination' } } }
+], { author: 'Editor' });
+```
+
+A changed-text header (`1. Old Terms` -> `1. New Terms`) takes two operations on the same paragraph in one batch: a
+`redline` of the text that keeps the typed marker exactly, and a `list-format` that converts the paragraph. The batch
+compiler allows this pair and always runs the redline first, whatever the batch order. The list-format then strips the
+unchanged marker. Accept All shows label `1.` with `New Terms`, and Reject All shows the literal `1. Old Terms`:
+
+```js
+await doc.applyOperations([
+  { type: 'redline', target: { exactText: '1. Old Terms' }, replacements: [{ find: 'Old', replace: 'New' }] },
+  { type: 'list-format', target: { exactText: '1. Old Terms' }, list: { mode: 'convert-plain' } }
+], { author: 'Editor' });
+```
+
+A redline in that pair that adds, removes or changes the marker is refused before anything is written, with
+`LIST_FORMAT_COMPOSITION_CONFLICT` (`reason: 'marker-changed'`). So is a redline that spans paragraphs or leaves the text
+unchanged. To give a paragraph without a typed marker a label, use `strip: 'none'` with `format` (and `start`). A
+`change-format` or `join` with `scope: 'list'` (the default) also writes every other item of the list. In the same batch,
+each of those items accepts only a single-paragraph `redline`; any other write to them fails with
+`LIST_FORMAT_COMPOSITION_CONFLICT` (`reason: 'list-rebind'`).
+Style-linked lists (heading numbering), mid-list splits, and markers inside hyperlinks or fields are refused with a
+recovery envelope. They are not approximated. Removing a list binding is `paragraph-format` with `properties.numbering:
+null`. A `list-format` `detach` mode is not available yet. See the
+[knowledge base](docs/AGENT_KNOWLEDGE_BASE.md#operation-model-choose-by-output-shape) for every mode, field and refusal.
+
 ### Planning large mixed-content insertions
 
 For an attachment or schedule containing several kinds of content, use
@@ -496,6 +580,7 @@ an earlier block has already replaced.
 | `analyzeStructuredContent(markdown)` | Decompose mixed Markdown into typed blocks and report malformed table syntax without creating an operation. |
 | `planStructuredReplacement(target, markdown, options)` | Validate mixed content and return one atomic `structuredContent` replacement operation, or `operation: null` with issues. |
 | `containsTrackedChanges(xmlDoc)` | Detect `w:ins`, `w:del`, move revisions, property changes, and paragraph-mark revision markup in a parsed OOXML document/fragment. |
+| `resolveExistingRevisionsPolicy(policy, node, author)` | Resolve `existingRevisions: 'auto'` for a parsed paragraph, scope element, or an array of range paragraphs: `'slice-cross-author'` when any tracked change is by another or an unattributed author, otherwise `'merge-same-author'`. Other policies are returned unchanged. |
 | `validateRedlineOoxml(oxml)` | Validate generated redline OOXML against the package's structural invariants (no nested revisions, `w:delText` inside `w:del`, complete metadata, unique revision ids, preserved boundary whitespace). Returns `{ valid, issues }`; run it before writing output into a package. |
 
 ### Services
@@ -503,13 +588,15 @@ an earlier block has already replaced.
 | Function | Purpose |
 |----------|---------|
 | `injectCommentsIntoOoxml(oxml, comments, options)` | Add comments anchored to text ranges. |
-| `applyCommentReplyToParts(options)` | Build a threaded reply in `comments.xml` and `commentsExtended.xml` without adding a document-body anchor. |
+| `applyCommentReplyToParts(options)` | Build a threaded reply in `comments.xml` and `commentsExtended.xml` without adding a document-body anchor. Pass `documentXml` so the reply's `w14:paraId` also avoids body paragraph ids. |
+| `compareDocumentInspections(expected, actual)` | Compare two `inspectDocumentParts` / `inspect()` results by text, table position, list label, review segments and comments, ignoring ids, dates and run boundaries. Returns `{ matches, differences }` (at most 10). See [Comparing inspections](#comparing-inspections). |
+| `inspectionReviewShape(inspection)` | The normalized, host-independent shape `compareDocumentInspections` compares. |
 | `acceptTrackedChangesInOoxml(oxml, { author?, allAuthors? })` | Accept `w:ins` / `w:del` / `w:moveFrom` / `w:moveTo` / `*PrChange` revisions for one author or all authors. |
 | `rejectTrackedChangesInOoxml(oxml, { author?, allAuthors? })` | Reject `w:ins` / `w:del` / `w:moveFrom` / `w:moveTo` / `*PrChange` revisions for one author or all authors. |
 | `deleteCommentsByAuthorInOoxml(oxml, { author?, allAuthors? })` | Delete matching comment definitions and anchors present in the supplied OOXML payload. Real `.docx` packages require updating both `word/comments.xml` and `word/document.xml`. |
 | `generateTableOoxml(headers, rows, options)` | Generate a `w:tbl` from tabular data. |
 | `createDynamicNumberingIdState(numberingXml)` | Allocate numbering IDs without collisions. |
-| `ensureNumberingArtifactsInZip(zip, numberingXml, options)` | Add numbering artifacts to a `.docx` package. Replacement of existing numbering without `mergeNumberingXmlBySchemaOrder` is deprecated and will throw in the next major version. |
+| `ensureNumberingArtifactsInZip(zip, numberingXml, options)` | Add numbering artifacts to a `.docx` package. Always merges into an existing `word/numbering.xml` through the package's single numbering merge (`mergeNumberingParts`); an incoming id that already exists with different content fails with `NUMBERING_ID_CONFLICT`. The former `mergeNumberingXml` option is ignored. |
 | `ensureCommentsArtifactsInZip(zip, commentsXml)` | Merge comments artifacts into a `.docx` package. |
 | `ensureCommentsExtendedArtifactsInZip(zip, commentsExtendedXml)` | Add or replace modern Word comment-thread metadata in a `.docx` package. |
 | `validateDocxPackage(zip)` | Validate `.docx` structural consistency. |
@@ -556,8 +643,9 @@ identities. Independent edits therefore do not need to be manually sorted when
 an earlier structural rewrite changes later paragraph indexes or fingerprints.
 Targets that deliberately refer to uniquely created paragraph text are compiled
 into an internal capture dependency. True overlap is not guessed: incompatible
-writes to one source fail before mutation with `OVERLAPPING_SOURCE_TARGETS` or
-`REVISION_ORDER_CONFLICT`, and mutating capture fan-out without distinct
+writes to one source fail before mutation with `OVERLAPPING_SOURCE_TARGETS`,
+`REVISION_ORDER_CONFLICT` or `LIST_FORMAT_COMPOSITION_CONFLICT` (the one composed pair, a
+marker-preserving `redline` plus a `list-format`, runs redline first), and mutating capture fan-out without distinct
 selectors fails with `CAPTURE_FANOUT_CONFLICT`.
 
 Threaded replies use a comment operation with no body target:
@@ -667,6 +755,57 @@ chooses among multiple candidate paragraphs heuristically, it emits an
 guidance. Callers should pass `{ strictTargets: true }` and use strict descriptors
 (`paragraphId`, `index`, `occurrence`, or `fingerprint`) to prepare for v1.0.0.
 
+### Reject All verification
+
+A tracked edit only adds revisions, so rejecting every revision in the output
+must give back the source document. After each operation the library projects
+Word's Reject All and Accept All of the output (`core/word-revision-semantics.js`,
+validated against recorded desktop Word results) and checks these invariants:
+
+- `REJECT_PARAGRAPH_COUNT`, `REJECT_PARAGRAPH_TEXT` (including tabs and breaks),
+  `REJECT_PARAGRAPH_PROPS`, `REJECT_NUMBERING_REFS` (list membership `numId`/`ilvl`)
+  and `REJECT_WRAPPERS` (hyperlink, field and content-control membership):
+  Reject All of the output equals Reject All of the source (under accept-first
+  `existingRevisions` policies the target range is compared with the source's
+  accepted view). `REJECT_NUMBERING_REFS` also refuses a `numId` that the output
+  binds, or Reject All restores (including inside `w:pPrChange`), when the source
+  did not already use it and no `w:num` -> `w:abstractNum` -> `w:lvl` in the
+  available numbering defines it.
+- `ACCEPT_INTENT`: a tracked plain-text `redline` with complete `modified` (no
+  Markdown, list-marker or table syntax; a single paragraph or a `targetEnd`
+  range) is refused when Accept All of its target would not read as `modified`.
+- `ACCEPT_NEIGHBORS`: an untracked edit (`generateRedlines: false`) may not
+  change a paragraph outside its target in the Accept All or Reject All view.
+- `UNTRACKED_CREATED_REVISION`: an untracked edit may not create a tracked
+  revision that was not in the source (fragments of a sliced source revision
+  keep their element, author and date and are allowed).
+
+A localized replacement is also checked before it is committed: the target's
+accepted text must equal the compiled replacement text, otherwise the operation
+is refused with `PATCH_ROUNDTRIP_MISMATCH` rather than dropping content.
+
+By default a violation is refused with `REVISION_FIDELITY_VIOLATION`; the
+document is unchanged, `status` is `error`, and the receipt is `refused`. The
+error payload contains:
+
+- `violations[]`, each with `invariant` (`REJECT_PARAGRAPH_COUNT`,
+  `REJECT_PARAGRAPH_TEXT`, `REJECT_PARAGRAPH_PROPS`, `REJECT_NUMBERING_REFS`,
+  `REJECT_WRAPPERS`, `ACCEPT_INTENT`, `ACCEPT_NEIGHBORS` or
+  `UNTRACKED_CREATED_REVISION`), a plain-language `explanation`,
+  `expected`/`actual` excerpts, and `source.sourceParagraphIndex` (the 1-based
+  paragraph index from extraction) with a text excerpt;
+- `recovery.retryGuidance`, one retry instruction per reported invariant, for
+  example use `replacements` for a literal edit, keep breaks and hyperlink
+  boundaries, or move formatting and list changes into their own operation.
+
+Control it with the `verifyRevisionFidelity` option (`'enforce'` default,
+`'warn'`, `'off'`) or `--revision-fidelity enforce|warn|off` on the CLI. `warn`
+applies the edit and appends the same text to `warnings`. The `--profile agent`
+profile rejects `off`. A narrower retry that is also refused indicates an
+unsupported shape; report it rather than disabling verification. Recovery
+details are in the `REVISION_FIDELITY_VIOLATION` row of
+[docs/AGENT_KNOWLEDGE_BASE.md](./docs/AGENT_KNOWLEDGE_BASE.md).
+
 ### Mutation Receipts
 
 Both single-operation (`applyOperationToDocumentXml`) and batch
@@ -722,7 +861,7 @@ Different APIs return different OOXML shapes. Use this as a packaging safety che
   ID. Generated bullet and numbered paragraphs must reference a positive ID
   whose definition is merged into `word/numbering.xml`.
 - Do use `extractReplacementNodesFromOoxml(...)` when you are consuming `result.oxml` from paragraph/range/table APIs.
-- Do merge numbering/comments artifacts with `ensureNumberingArtifactsInZip(...)` and `ensureCommentsArtifactsInZip(...)` when those parts are present. Supply `mergeNumberingXmlBySchemaOrder` when numbering already exists.
+- Do merge numbering/comments artifacts with `ensureNumberingArtifactsInZip(...)` and `ensureCommentsArtifactsInZip(...)` when those parts are present. Numbering is always merged, never replaced; pass `numberingXml` or a shared `numberingIdState` to every call so generated ids cannot collide.
 - Don't write payloads that start with `<pkg:package` directly into `word/document.xml`.
 - Don't assume every `result.oxml` payload is a raw paragraph fragment.
 
@@ -744,7 +883,6 @@ import {
   applyRedlineToOxml,
   extractReplacementNodesFromOoxml,
   ensureNumberingArtifactsInZip,
-  mergeNumberingXmlBySchemaOrder,
   validateDocxPackage
 } from '@ansonlai/docx-redline-js';
 import { applyOperationToDocumentXml } from '@ansonlai/docx-redline-js/standalone-runner';
@@ -807,9 +945,7 @@ const normalized = extractReplacementNodesFromOoxml(fragmentResult.oxml);
 // If sourceType === 'package', merge extracted content/artifacts instead of
 // writing the raw pkg:package payload into word/document.xml.
 if (normalized.numberingXml) {
-  await ensureNumberingArtifactsInZip(zip, normalized.numberingXml, {
-    mergeNumberingXml: mergeNumberingXmlBySchemaOrder
-  });
+  await ensureNumberingArtifactsInZip(zip, normalized.numberingXml);
 }
 
 await validateDocxPackage(zip);