The Complete Production SOP: How to Deploy and Run python-docx Track Changes & Comments Audit in Autonomous AI Agents

---
name: "python-docx-track-changes-audit"
description: "Inspect, review, and manipulate Word revisions, track changes, and reviewer comments."
metadata:
  author: "python-openxml"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "audit track changes in docx"
  - "extract comments from word python"
  - "detect unaccepted revisions docx"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

# python-docx Track Changes & Comments Audit

Parses OpenXML markup in .docx files using Python to detect insertions (<w:ins>), deletions (<w:del>), reviewer comments (<w:comment>), and author metadata for compliance auditing.

## When to Invoke
- audit track changes in docx
- extract comments from word python
- detect unaccepted revisions docx

## Execution SOP & Rules
1. Treat .docx files as zip archives; extract and parse `word/document.xml` using `lxml.etree`.
2. Query namespace `xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"` for `<w:ins>`, `<w:del>`, and `<w:commentReference>`.
3. Read `word/comments.xml` to map comment IDs to original author strings, dates, and comment body text.
4. Produce a structured JSON compliance report containing author, timestamp, change type, and text content before proceeding with any acceptance/rejection write operation.

import zipfile
from defusedxml.lxml import fromstring
from typing import Dict, List, Any

NS = {'w': 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'}

def audit_docx_revisions(docx_path: str) -> Dict[str, Any]:
    report = {'insertions': [], 'deletions': [], 'comments': []}
    with zipfile.ZipFile(docx_path, 'r') as doc:
        if 'word/document.xml' in doc.namelist():
            root = fromstring(doc.read('word/document.xml'))
            for ins in root.xpath('//w:ins', namespaces=NS):
                text = ''.join(ins.xpath('.//w:t/text()', namespaces=NS))
                report['insertions'].append({
                    'author': ins.get(f'{{{NS["w"]}}}author', 'Unknown'),
                    'date': ins.get(f'{{{NS["w"]}}}date', ''),
                    'text': text
                })
            for deletion in root.xpath('//w:del', namespaces=NS):
                text = ''.join(deletion.xpath('.//w:delText/text()', namespaces=NS))
                report['deletions'].append({
                    'author': deletion.get(f'{{{NS["w"]}}}author', 'Unknown'),
                    'date': deletion.get(f'{{{NS["w"]}}}date', ''),
                    'text': text
                })
        if 'word/comments.xml' in doc.namelist():
            croot = fromstring(doc.read('word/comments.xml'))
            for c in croot.xpath('//w:comment', namespaces=NS):
                text = ''.join(c.xpath('.//w:t/text()', namespaces=NS))
                report['comments'].append({
                    'id': c.get(f'{{{NS["w"]}}}id'),
                    'author': c.get(f'{{{NS["w"]}}}author', 'Unknown'),
                    'text': text
                })
    return report

{
  "status": "AUDIT_COMPLETE",
  "unacceptedRevisionsCount": 2,
  "commentCount": 1,
  "revisions": [
    {
      "type": "w:ins",
      "author": "ExternalCounsel",
      "date": "2026-03-28T14:12:00Z",
      "text": "Liability shall be capped at 50,000 USD."
    },
    {
      "type": "w:del",
      "author": "LeadNegotiator",
      "date": "2026-03-29T09:20:00Z",
      "text": "Unlimited indemnity applies to all breach conditions."
    }
  ],
  "comments": [
    {
      "id": "1",
      "author": "SecurityAuditor",
      "text": "Verify indemnification terms before signing."
    }
  ]
}

import unittest
import zipfile
from scripts.audit_revisions import audit_docx_revisions

class TestDocxAudit(unittest.TestCase):
    def test_audit_structure(self):
        result = audit_docx_revisions('tests/fixtures/sample_redline.docx')
        self.assertIn('insertions', result)
        self.assertIn('deletions', result)
        self.assertIn('comments', result)
        self.assertIsInstance(result['insertions'], list)

    def test_zip_integrity(self):
        with zipfile.ZipFile('tests/fixtures/sample_redline.docx', 'r') as doc:
            self.assertIsNone(doc.testzip(), 'DOCX archive contains corrupted zip headers')

if __name__ == '__main__':
    unittest.main()