Word Documents for Human Review

Verification Scripts

All four live under .agents/skills/docx/scripts/ and print JSON to stdout, except render.py which prints paths; --help on any of them prints the full usage with every subcommand and flag; a flag none of them names, or one repeated or left without its value, is refused before any work starts, so a misspelt --out cannot rewrite the file it was meant to leave alone.

render.py <file> [--out DIR] [--dpi N] [--keep-pdf]: pages to PNG through LibreOffice and pdftoppm, with an ODT fallback for documents the direct route refuses. Look at every page. Two things do not survive the trip: comment balloons never appear, and a TOC field shows its placeholder because only Word acts on w:updateFields. Tracked changes do render, marked up, so check final layout on a redline.py accept copy.

redline.py report|accept|reject|replace|insert|delete <file> [...]: report lists every revision with id, type, author, date, paragraph index and text, across the body, headers, footers and notes; --paragraphs adds the indexed paragraph list. accept and reject resolve everything and write a copy (default <stem>_accepted.docx / <stem>_rejected.docx), handling content, paragraph marks, table rows and property changes. A tracked cell insert or delete is replayed as the cell itself, kept or removed along with any row it empties, while a cellMerge stops the run with its table and cell named, because a merge absorbs the cells it joins and neither side can be rebuilt from what the file still holds. A numberingChange stops a reject the same way with its paragraph named, because the element records the shape of the previous numbering and not the w:numId and w:ilvl that would have to go back, while accept keeps the current numbering and drops the marker; a numbering change recorded as a w:pPrChange carries the whole previous w:pPr and resolves normally either way. Numbering the reviewer added does resolve: w:numPr/w:ins reports as numbering-insert, accept keeps the numbering and drops the marker, and reject takes the whole w:numPr so the paragraph goes back to unnumbered. For a final copy run comments.py strip afterwards and confirm with validate.py --final; accepted revisions do not remove the review comments. replace --find "old" --with "new" marks a tracked deletion plus insertion, splitting runs as needed so a phrase spanning a bold boundary still matches; --paragraph N scopes it, --all takes every occurrence. insert --after-paragraph N --text and delete --paragraph N are tracked too. These three write in place unless --out is given.

{"status": "ok", "action": "replace", "count": 1,
 "edits": [{"paragraph": 5, "find": "up 8 percent", "with": "up 8.4 percent", "del_ids": [1], "ins_id": 2}]}

comments.py list|add|reply|resolve|strip <file> [...]: list returns each comment with author, date, text, the text it is anchored to, the part and paragraph it is anchored in, resolved, and parent_id for replies; a comment can be anchored in a header, footer or note as well as the body, and reply threads into whichever story holds it. add --paragraph N [--find "text"] anchors on a paragraph or a substring; reply --to ID threads under a comment, and a reply aimed at another reply joins that same thread because a thread is the only shape Word renders; resolve ID marks the whole thread done; strip deletes every comment, reply and in-text anchor, along with commentsExtended.xml, commentsIds.xml, commentsExtensible.xml and people.xml, which is how you produce a final copy that carries no review traffic; people.xml goes because it names the reviewers and the directory ids behind them long after their comments are gone. The commands maintain commentsExtended.xml alongside comments.xml, which is what makes replies thread and resolution stick.

validate.py <file> [--strict] [--final]: package integrity (zip, content types, relationship targets), heading hierarchy and style use, table header rows and widths, placeholder tokens and bad characters, metric-safe fonts across the body, headers, footers and notes, TOC field wiring, and a count of what is still under review. fail blocks delivery, warn is a judgement call, info is context. Tracked changes and comments are info by default because a review copy is meant to carry them; --final is the gate on the clean copy, where those nodes come back at fail as final_revisions for the stories and final_comments for the comment parts, joined by final_people for a surviving reviewer roster. The tracked-change count spans the comment parts as well as the stories, because a comment body holds block content and a reviewer can leave a revision inside one; redline.py accept does not reach those, comments.py strip removes them with the comment.

It also checks element order. ECMA-376 gives w:pPr, w:tblPr, w:tblPrEx, w:tcPr and w:sectPr a fixed child sequence, and pins the revision markers and change records inside w:rPr and w:trPr; Word offers to repair a file that breaks it, LibreOffice renders it without complaint, so a bad order survives the render and fails for the reader. The xml_order check walks the body, headers, footers and notes and names the inverted pair, as in document.xml p12 w:pPr pStyle after jc. The build snippet above writes the PAGE and TOC fields, tblHeader and cantSplit by hand, so run the check on your own output as well as on a file that arrived from somewhere else.

Pitfalls

• python-docx cannot see tracked changes. paragraph.text and paragraph.runs return only direct w:r children, so both inserted and deleted text vanish from the string. A redlined paragraph reads as if the change never happened. Use pandoc --track-changes=... or redline.py report.
• Two paragraph numberings exist. These scripts index every w:p in document order including table cells; document.paragraphs skips table paragraphs. On a document with a table the two never agree. Take indices from redline.py report --paragraphs.
• A replacement inherits the first matched run's formatting. Replacing text that starts inside a bold run makes the whole replacement bold. Scope the match to one formatting run, or fix the run properties after.
• Do not use w: elements as booleans. An lxml element with no children is falsy, so if paragraph.find(...) is a silent bug; test is not None.
• Comments are unusable without paraIds. A comment part written without w14:paraId on each comment paragraph gives Word a flat list with no replies and no resolve button. comments.py backfills them.
• Deleting the last paragraph's mark has nothing to merge into. redline.py accept warns and leaves an empty paragraph; delete a paragraph that has a successor.
• add_heading(text, 0) applies Title, not Heading 1. Levels 1 to 9 map to Heading N.
• A run is a formatting span, not a word. python-docx splits text into runs on every property change, so string operations across paragraph.runs see fragments.
• cell.text = value replaces the cell's whole content and drops its formatting; write into cell.paragraphs[0] when the cell is already styled.
• .docm keeps macros in a part python-docx round-trips but never validates; do not convert one to .docx.

Deliverable Checklist

• validate.py reports no fail; every rendered page inspected.
• Headings are real styles in an unbroken hierarchy; body text is styled, not directly formatted.
• Tables have a repeating header row, declared widths, and fit the text area.
• A TOC, if present, is a field with w:updateFields set.
• On an edit: every change is tracked and attributed, every human comment answered or resolved, and the untouched parts of the file are untouched.
• The file is at <task>/<descriptive_name>.docx and the reply names it, says whether it carries tracked changes, and lists what still needs the user's decision.