fix(comments): new comments are not registered in commentsIds.xml, so Word offers to repair the file #33

Version: docx-cli 0.28.0, release binary (Windows x64), Windows 11, Word 16 (365).

What happens

comments add writes the comment into word/comments.xml and the
commentRangeStart / commentRangeEnd / commentReference into word/document.xml, but does not
add the matching w16cid:commentId to word/commentsIds.xml, nor a w15:commentEx to
word/commentsExtended.xml. On a Word-saved input — i.e. any real document — the package is left
inconsistent from the first added comment onwards, and Word shows "This file contains unreadable
content. Recover?" on open.

Repro

Attached: fixture-comments-base.docx (7.6 KB). It is a clean package with 2 comments and all
three parts populated 2 / 2 / 2; the side-parts carry Word's shape (w16cid:commentId with
paraId+durableId, w15:commentEx with paraId+done, both keyed to the comment paragraph's
w14:paraId), and docx validate reports valid — 6 parts checked.

$ docx comments add fixture-comments-base.docx --anchor "dritte Absatz" --text "Dritter Kommentar." --author "Test Reviewer"
c2

docx validate still reports valid — 6 parts checked afterwards.

Evidence from the document that hit it

18.5 MB report, 63 pages, 2'366 paragraphs, 25 comments, saved by Word before the session. After the
session the parts stood at 25 / 3 / 4 — the 3 and 4 are the comments the file already had and its two
reply threads. Word offered recovery and rebuilt both side-parts:

Comment texts and anchors survive the repair unchanged, but comment ids are renumbered (measured:
c23 → c105, c28 → c49, c40 → c598), so any external reference to a comment handle is
invalidated by it. That is what makes this more than cosmetic: the reviewer is handed a repaired copy
of the file they were asked to redline, with every handle shifted.

Expected

One commentId and one commentEx per comment, keyed by the comment's paragraph w14:paraId,
written on comments add and removed on comments delete — the shape Word itself writes.

Where it likely lives

src/cli/comments/add.tsx contains no reference to commentsIds, commentsExtended or paraId.
A reply does produce an entry (measured: 4 comments, one a reply → 2 commentEx entries), so the
write path exists in the reply flow — likely through the CommentsView that CLAUDE.md describes as
owning the part. This looks like one omitted registration plus a missing rebuild path; I did not read
the save path far enough to name the call site.

Suggested regression test

tests/cli/comments.test.ts: on a fixture whose side-parts already list its comments, after two
comments add the entry count in commentsIds.xml and commentsExtended.xml equals the comment
count. The attached file is exactly that fixture, so it can become tests/fixtures/comments-base.docx
as-is.

Notes

• docx create never writes commentsIds.xml, and commentsExtended.xml only appears once a
  reply is added (measured: 4 comments → 2 entries). A purely docx-cli-produced file is therefore
  consistent (parts absent, not stale). The breakage is specific to Word-authored input.
• If an input's side-parts are already partial, rebuild them from comments.xml rather than append.
  docx comments rebuild-parts FILE would also let files written by 0.28.0 be repaired without
  opening Word.
• Related, but a different mechanism: Threaded replies are added but not rendered #1, fix: anchor comment replies and cascade delete through thread descendants #2, fix: anchor comment replies in the body, mint valid paraIds, cascade thread delete #3 (threading, paraId minting). validate not seeing
  this is filed separately.

fixture-comments-base.docx