[kklimuk]

🤖 docx-cli triage

What was wrong

docx validate only schema-checks each part, so cross-part comment breakage went unreported. Repro: cp tests/fixtures/academic-paper.docx a.docx && docx comments add a.docx --at p1 --text "new note" && docx validate a.docx printed valid — 11 parts checked, exit 0. The new comment has no entry in commentsIds.xml or commentsExtended.xml, which is the Word repair trigger reported in #33.

What changed

• New pure audit src/core/raw/package-consistency.ts (checkPackageConsistency). validate runs it alongside the schema pass, over the same parsed parts. It checks:
  • every comment has an entry, keyed by its last paragraph's w14:paraId, in each side part that is present (commentsExtended.xml, commentsIds.xml). A side part that is missing entirely is legal and not reported.
  • comment markers balance across the body, headers/footers and footnotes/endnotes: each range start has a range end, each range has a commentReference, and each reference names a comment that exists.
• Each finding is listed under the part it concerns, tagged (consistency) in text output and kind: "consistency" in --json, and it makes validate exit 1. Not reported on purpose, to avoid noise: orphan side-part entries, comments with no markers in the document, ids that appear more than once because of mc:AlternateContent (compared as sets), and the glossary document.
• The raw gate is unchanged: it still judges a raw edit on schema errors only.
• Docs: --help, REFERENCE.md, the skill's commands.md, src/cli/CLAUDE.md, src/core/raw/CLAUDE.md.

Verification

• Same repro after the change: exit 1 with

  word/commentsExtended.xml: 1 error
    comment c44 (paraId 25858A85) has no entry in word/commentsExtended.xml (consistency)
  word/commentsIds.xml: 1 error
    comment c44 (paraId 25858A85) has no entry in word/commentsIds.xml (consistency)
  

• Every shipped fixture still validates clean (the existing "every fixture validates clean" test guards against false positives). That includes the Word-authored academic-paper.docx, which has all three comment parts.
• 6 new tests in tests/cli/validate.test.ts built from hand-made inconsistent packages: missing commentsIds entry, a consistent commentsIds, a range whose reference was deleted, an unpaired range start, a dangling reference (--json), and a clean commented doc.
• bun run check ✅ bun run test:unit ✅ (1915 tests)
• /simplify (one pass, no Agent tool): dropped one redundant filter. /code-review xhigh: the forked run reviewed the wrong checkout (see the triage report), so I reviewed this diff by hand instead. That review added the glossary exclusion; nothing else changed.

Decisions for you

• Surface: I extended validate instead of adding the docx check verb the issue suggests, so agents keep a single "is this safe to deliver?" command with one exit code. Should this be a separate verb or a flag instead?
• Severity: findings are errors (exit 1), not warnings, because weak agents ignore warnings when the exit code is 0. Word's behavior is still unverified for one case: a comment missing from commentsExtended.xml alone. Verified repair triggers are measured only for the combined fix(comments): new comments are not registered in commentsIds.xml, so Word offers to repair the file #33 state.
• Merge order with fix(comments): new comments are not registered in commentsIds.xml, so Word offers to repair the file #33: until fix(comments): new comments are not registered in commentsIds.xml, so Word offers to repair the file #33 is fixed, docx-cli's own normal flow fails this check. For example, comments add → comments reply → comments add leaves the third comment without a commentsExtended.xml entry, so validate exits 1. That is correct (it is the fix(comments): new comments are not registered in commentsIds.xml, so Word offers to repair the file #33 bug), but users will see it. Merge this together with or after the fix(comments): new comments are not registered in commentsIds.xml, so Word offers to repair the file #33 fix.
• Scope: a check that relationships point at existing parts (the issue's second priority) is left for a follow-up.

Action needed: approve/merge — review the decisions above, ideally merging after #33's fix lands.

Fixes #34

---

Generated by Claude Code