ooxml-integrity

ooxml-integrity checks .docx and .pptx files after automated editing. It finds broken comment anchors, lost tracked changes, orphaned footnotes, and presentation text that is likely to overflow its box.

The checker reads the document package and local font files. It runs locally, without rendering, model calls or network access, so documents can stay on your machine.

The browser demo runs without installation. Files stay in your tab; Python downloads once at startup. The demo pins a published release, updated after each one, and reports its version in the footer. Real browser checks gate changes before Pages deployment. Releases are published on PyPI; each one's upgrade notes describe changed findings and compatibility.

pip install ooxml-integrity
ooxml-integrity check edited.docx --against original.docx

edited.docx: 2 error(s), 0 warning(s), 0 info
  [ERROR] CMT005  comment id=1 is orphaned - present in comments.xml but
                  anchored to nothing - the reviewer's note is invisible in Word
  [ERROR] FID001  comment anchors: 2 -> 1 (1 lost)

In this example, the edited file opens in Word without a warning and keeps the same word and page counts. The reviewer's note, "Confirm this figure against the source table before circulation", is still inside the package, but its anchor is gone and Word no longer shows it beside the figure.

Why this exists

I started with a small experiment: ask agents to edit a contract that already contains reviewer comments and tracked changes. In two runs, the task was to update three figures in the same table. The run labelled careful preserved the comment and recorded the edits under a separate author. The fast run used python-docx and lost the comment anchor:

The cause is a paragraph replacement. Assigning paragraph.text in python-docx replaces the paragraph's contents with a new run. That also removes comment anchors, footnote references, run formatting and tracked-change markup stored there. The file can still open normally after those losses.

In a separate test with six deliberately introduced defect cases, the checker found all six: five by checking the edited file alone, and a Markdown round trip, which leaves the file internally consistent, only by comparing it with its source (--against). XML parsing, a namespace/root-element check and successful LibreOffice PDF conversion did not distinguish those cases from the controls. The experiment did not run a full XSD validator or a systematic visual review. Across the eight real agent runs, the checker reported no false positives.

The research notes describe the experiments, saved outputs, renderer measurements and limitations.

Related MCP server: sheetspec

Tools and agents on a reviewed document

Eight runs could only suggest a pattern. The review-history benchmark gave 30 ordinary requests (replace a phrase, reply to a comment, accept one revision, fix a footnote) on two contracts with a live review history to six document tools, python-docx on two code paths, and three coding agents in sealed containers. An oracle that never imports the checker compared each output with its source, and one output per kind of damage was opened in Word for Mac.

• Claude Code (Opus 5.5) and Codex (gpt-6.1-sol) completed and preserved all 150 attempts each, five captures apiece. In every capture Codex's reply to the first contract's comment had no anchor in the document, and Word for Mac does not show such a reply. OpenCode with a local Qwen3.8 27B once removed another reviewer's insertion wrapper, so that reviewer's pending sentence read as accepted text.

• Assigning Paragraph.text or _Cell.text in python-docx damaged 14 of 28 outputs. docx-cli damaged 38 of 56: bullets turned into the literal text •, and new words were credited to another reviewer. Two tools edited the document title instead of the requested header.

• Of 69 damaged outputs, the frozen checker (0.4.6) reported 41, and it flagged 145 of 537 correct outputs, mostly for the requested change itself. 0.4.9, with each task's requested change declared as expected, reports 65 and flags 12, each a true report outside the benchmark's scope, such as a reply Word does not show.

Counts are attempts on two documents, not independent documents. The evidence has the frozen protocol, its amendments and every capture.

Applied to other projects

Findings from the corpus and the benchmark were filed upstream, each with a self-contained reproduction. adeu fixed two and docx-cli three; the others are open.

Fixture contributions merged upstream: adeu #138 (comment projection across LibreOffice, Word for Mac and Word for Windows) and adeu #140 (revision projection and accept/reject). Preparing them surfaced a Python/TypeScript namespace-serialization mismatch in adeu's own consistency suite (#139, fixed in 3.0.4).

In use upstream: since adeu #156 (merged 2026-09-29), adeu's test suite installs ooxml-integrity, pinned to 0.4.8 since adeu #161 (merged 2026-10-05). For each shared cross-platform scenario it applies the edits, runs check() on the output and compare() against the input, and fails on error-level findings. The two accept/reject scenarios declare the revision-count changes they request as expectations with expect().

Two questions

A document can lose all its styles, footnotes and revisions and still be internally consistent. The checker therefore supports two kinds of inspection.

Are the internal references intact? Check comments, footnotes, styles, numbering, relationships and tracked changes within one file.

ooxml-integrity check report.docx

What did the edit lose? Compare construct counts and text with the source. This can find losses even when the edited file has no broken references.

ooxml-integrity check edited.docx --against original.docx

When the original may already be broken, as with a document a user uploads to an agent, add --introduced (0.10.0) to fail only on what the edit added. A finding the original already has is listed as suppressed instead; lost content always counts. What counts as the same finding.

Exit codes are 0 for no findings at or above --fail-on (default error), 1 when such findings exist, and 2 for a usage error. Use --json for machine-readable output and --quiet to print only findings that fail the run.

Three repairs, and no more

Most findings cannot be repaired from the file: putting back a lost comment, style or tracked change means guessing what was there. fix makes only the three repairs whose result is unique, and checks the copy again before writing it.

ooxml-integrity fix edited.docx -o repaired.docx

• anchor-replies (CMT005): a reply whose parent comment is anchored is given its parent's range, in the order Word writes a thread. In Word for Mac, the reply appears in its thread only after the repair.

• renumber-revisions (REV001): every repeated revision id after the first gets a fresh id.

• content-type (PKG010): a related part's Override in [Content_Types].xml gets the content type its relationship type requires. Word for Mac refused all five Codex outputs that fix repairs this way, and opened the copy fix writes from one of them, with the reply in its thread.

Every other finding is listed as not repaired, with the reason. The input is never changed. In the copy, only the repaired bytes differ, and every other ZIP member is copied as stored. Exit 0 means a verified copy was written; 1, nothing to repair; 2, a usage error or a package fix does not rewrite; 3, a failed re-check. What it repairs, refuses and guarantees.

Decks: does the text fit the box?

ooxml-integrity check deck.pptx

deck.pptx: 6 error(s), 4 warning(s), 1 info
  [ERROR] PPT001  text needs 144pt in a 40pt box - 104pt too tall (260% over), 3 line(s)
            -> slide1/OVER_huge_type_tiny_box
  [ERROR] PPT003  word wrap is off and the longest line is 304pt in a 182pt box
                  - 122pt runs outside the shape
            -> slide2/OVER_nowrap_single_line
  [WARN ] PPT004  shape extends 142pt past the right edge - content will be cut off
            -> slide3/OFFCANVAS_right
  [WARN ] PPT006  overlaps 'OVERLAP_upper_right' over 23% of the smaller shape
            -> slide3/OVERLAP_lower_left

Text fitting requires the effective font and size, which may be inherited through runs, paragraphs, list styles, layout and master placeholders, presentation defaults and themes. The checker resolves these values and reads widths from the font's hmtx/cmap tables through fontTools. The related python-pptx discussion describes the need for text measurement when fitting text.

In the reference-deck check against PowerPoint for Mac, all 21 checkable shapes matched the predicted verdict and line count. Other renderers disagreed on a shape close to its width limit. The checker reports predicted vertical overflow of up to 5% as PPT002 borderline, and missing fonts as PPT007. The validation record gives the method and the limits of that comparison.

Later checks in 0.4.0 cover long basic-Latin words, TTC/OTC font members, presentation slide order and each slide master's Latin theme fonts. Their four dedicated decks add 29 recorded PowerPoint slide observations. The long-token, font-collection, slide-order and theme notes record the cases and their remaining limits.

In CI

- uses: Dmitry-Kov/ooxml-integrity@v0.10.0
  with:
    files: "out/**/*.docx"
    against: templates/master.docx   # optional, enables the fidelity check
    fail-on: error

Run the check after a generation script, agent edit or template merge, while the source and edited files are still available for comparison.

The action writes a summary to the job page and can produce JSON and SARIF reports. SARIF findings can appear as code-scanning annotations in a pull request. The configuration guide covers severity overrides, path-scoped ignores with a required reason, and counted baselines for repositories that already have findings.

From an agent

claude mcp add ooxml-integrity -- ooxml-integrity mcp

An agent can run the same checks on a document it has just edited, before it returns the file. ooxml-integrity mcp is a local MCP server with two tools, check and compare; it talks over stdin and stdout and opens no socket. A call returns the report of check --json --coverage and a one-line verdict. The MCP guide has the configuration for Claude Code, Codex and OpenCode.

From Python

from ooxml_integrity import check, compare

for f in check("edited.docx"):
    print(f.code, f.severity.value, f.message, f.where)

for f in compare("original.docx", "edited.docx"):
    print(f.code, f.message)

Python 3.9+. Two dependencies: lxml, fonttools (plus tomli on 3.10 and older, only to read the config file). If the console script is not on your PATH, python -m ooxml_integrity check report.docx works anywhere.

What it reports, and how much it covered

Every finding has a stable code and severity, plus a part, shape or XPath where one can be identified. Losses that hide content or its audit trail are errors. Losses that affect only appearance are warnings. Undefined paragraph and table styles remain errors because they can carry numbering and structure; undefined character styles are warnings. These tables describe 0.10.0. Version 0.4.0 treated undefined character styles as errors; use --fail-on warn to keep them failing after upgrading.

.docx:

.pptx:

Use --coverage to see the scope of a result. It distinguishes checked, not-present, estimated, skipped and unsupported surfaces per file, and a result with a gap says no findings in checked surfaces, not clean. ooxml-integrity doctor reports which measurements are available on the current machine. See the support matrix and coverage and doctor.

Limitations

• The DOCX evidence corpus uses 50 synthetic sources and 220 labelled pairs across five producers (Word for Windows, Word for Mac, Word Online, LibreOffice, python-docx): 120 clean controls and 100 seeded-defect pairs. The recorded result has 111 error-level true positives, zero false positives and zero false negatives. The 100% precision and recall apply to that corpus and the 14 rules it labels; the other rules are not measured there. Accuracy on customer documents has not been measured.

• A separate existing-revision tranche has 30 pairs: 15 controls preserving review content through adeu, Word Online and Word for Windows, nine seeded defects (historical checker revision: seven detected, two missed; 0.4.2 FID009/FID010 follow-up: nine detected), and six accept/reject characterizations excluded from preservation metrics. Producer groups are reported separately. The three Windows saves preserve revisions but change table widths; unchanged layout and broader Office review operations remain unmeasured.

• The review-history benchmark used two contracts written for it, one version of each tool and agent, and one build of Word for Mac to confirm each kind of damage. It compares review content, not formatting or layout.

• PPTX evidence comes from PowerPoint for Mac editing-view checks and native exports of the later regression decks. Windows and Slide Show mode are untested. GPOS kerning and shaping are not applied, so complex scripts and heavily-ligatured faces are estimates.

• Grouped shapes, tables, SmartArt and charts in decks are not modelled. Rotated-shape geometry is only partially checked.

• Only the Carlito/Calibri metric-compatible pairing has been measured.

The full list, with the numbers behind each, is in docs/research.md.

Where this is going

The benchmark showed that tools and agents given the same request can preserve or lose review information on the same document, and that a checker told which change was requested separates the two. Its documents were written for it. The next question is how the checker does on real reviewed documents and the edits real pipelines make to them.

If your workflow includes automated DOCX edits followed by human review, try a 30-minute pilot with one local before/after pair. Share feedback about a useful finding, false alarm, missed defect or setup problem. Include the generator and checker versions, finding code and expected/actual behavior. GitHub reports are public; attaching a document is optional.

To attach a confidential pair, anonymize it first. The copies keep the structure and lose the text, authors, dates, properties and pictures, and the command checks that every finding is still there:

ooxml-integrity anonymize original.docx edited.docx -o share/

What it replaces, what a reader can still learn, and how it was measured.

Contributing and compatibility

See CONTRIBUTING.md for reproducible reports, development setup, evidence requirements and the checks relevant to a PR. Compatibility and upgrades explains rule codes, severity, JSON/coverage versions, baseline migration and changes that can affect a CI gate even in a patch release. For sensitive vulnerability reports, use the private channel in SECURITY.md.

Repository layout

src/ooxml_integrity/   inspector, fidelity, fonts, pptx layout and checks,
                       coverage, doctor, policy, sarif, cli, MCP server
tests/                 labelled-corpus, story-fidelity and false-positive regressions
research/              corpus builders, mutators, calibration, renderer comparison
docs/                  research notes, configuration, support matrix, validation records
demo/                  browser checker, landing page, bundled fonts and examples
corpus/                reference .docx and .pptx, byte-reproducible
evidence/docx-beta/    50 producer sources and 220 labelled DOCX pairs
evidence/docx-revisions/  30 pairs with existing revisions and explicit known misses
evidence/review-history-benchmark/  frozen protocol, tool and agent captures, evaluation
runs/                  the first eight agent outputs, used as fixtures
action.yml             the GitHub Action

License

MIT.