Tracking: word-aligned-state-sync round-trip 驗證線（XmlNode tree + .mdocx Swift 腳本）

[kiki830621]

Problem

Original text:
「我記得che-word-mcp有一個大改動，就是想要用round test確保word修改不會有差的，我會建立swift腳本來測試，想看看目前到哪裡了」
— Source: 使用者直接輸入（2026-07-03 session）

使用者記憶中的「che-word-mcp 大改動」對應到 macdoc 的 Spectra change word-aligned-state-sync（把 ooxml-swift 從破壞性 typed model 改造為 lossless XmlNode tree + operation log + .mdocx Swift 腳本授權面）。此 issue 是該線的 GitHub tracking 入口 —— 之前進度只存在 openspec/changes/word-aligned-state-sync/ 裡，跨 repo 的 round-trip 損失 bugs 沒有單一 dashboard。

Type

tracking（feature line）

Priority

P2（排程）— 回鍋此線時可升級

Current Status (2026-07-03)

Spectra change word-aligned-state-sync：10/73 tasks

Phase	內容	目標版本	狀態
Phase 0	XmlNode tree 基礎（lossless 表示、identity round-trip、golden corpus、TreeRoundTripGoldenTests）	ooxml-swift v0.30.0	✅ 10/10 完成，已釋出
Phase 1	typed views 變 tree projections（Paragraph/Run/Table/SectionProperties/Settings）	v0.31.0	○ 未開始
Phase 2	Operation log（append-only + JSONL sidecar + reducer/undo/blame）	v0.32.0	○ 未開始
Phase 3	Word-import diff / SyncOrchestrator（conflict 偵測、file watcher、Word lock）	v0.33.0	○ 未開始
Phase 4	Script transcoder（op log ↔ .mdocx Swift 腳本、log→script→log round-trip、macdoc word reverse CLI）	v0.34.0	○ 未開始
Phase 5	v1.0.0 遷移清理（移除 legacy typed-only 路徑）	v1.0.0	○ 未開始

已鎖定 specs：ooxml-roundtrip-fidelity、ooxml-roundtrip-completeness、mdocx-grammar（.mdocx 語法 locked，transcoder 實作在 Phase 4）
既有測試面：ooxml-swift RoundTripFidelityTests / TreeRoundTripCorpusTests / TreeRoundTripGoldenTests / DocumentXmlLosslessRoundTripTests 等；che-word-mcp RealWorldDocxRoundTripSmokeTests
姊妹 change：ooxml-edit-isomorphism-foundation（11/35）

關聯的 round-trip 損失 bugs（ooxml-swift，open）

Phase 0 的 tree 表示是這些 bug 的結構性解法；Phase 1 落地後應逐一回頭驗證：

• VML / wps / wpg shape elements lost during round-trip (sister concern from kiki830621/collaboration_guo_analysis#20) ooxml-swift#62 — VML / wps / wpg shape elements lost during round-trip
• mc:AlternateContent block dropped during round-trip (sister concern from kiki830621/collaboration_guo_analysis#20) ooxml-swift#63 — mc:AlternateContent block dropped during round-trip
• Multi-section <w:sectPr> structure collapses to single generic sectPr — headerReference / footerReference lost ooxml-swift#67 — Multi-section sectPr collapses（headerReference / footerReference lost）
• [bug] settings.xml round-trip loss (~19KB → ~400 bytes) — same skip pattern as #67 ooxml-swift#69 — settings.xml round-trip loss (~19KB → ~400 bytes)

Expected

• .docx 經 read → mutate → save 後，未被編輯的部分零損（round-trip fidelity）
• .mdocx Swift 腳本可作為驗證面：log → script → log 等價、script → docx 可迭代（Phase 4；即使用者想寫的 Swift 測試腳本歸屬處）
• 上列 4 個 ooxml-swift round-trip bugs 隨 phase 推進逐一清空

Actual

• Phase 0 完成（tree 基礎 + golden corpus 已 merge、v0.30.0 已 tag）
• Phase 1–5 未開始：typed views 尚未接上 tree，4 個 round-trip bugs 仍 open
• .mdocx 語法已 locked 但 transcoder 未實作，Swift 腳本驗證還不可用

Impact

沒有這條線，任何經 che-word-mcp / ooxml-swift 寫回的 .docx 都可能靜默丟失未觸碰的內容（shapes、AlternateContent、多 section 結構、settings）—— 對使用者是不可逆的文件損壞風險。

Next Steps

1. /spectra-apply word-aligned-state-sync 續作 Phase 1（typed views → tree projections，v0.31.0）
2. Phase 1 落地後回頭驗證上列 4 個 bugs
3. Phase 4 建立 .mdocx Swift 腳本 round-trip 驗證

Clarity Surface(idd-clarify run 2026-07-03T03:53:43Z)

Type	Source	Suggested canonical	Status
ambiguity	"想要用round test確保word修改不會有差的"	「round test」非標準術語；候選解讀：(a) round-trip fidelity test（read→write 無損驗證，body 採此解）；(b) 一般 regression test suite	surfaced
ambiguity	"我會建立swift腳本來測試"	「Swift 腳本」雙解：(a) .mdocx script transcoder 驗證面（Phase 4，body 採此解）；(b) 一般 XCTest Swift 測試碼（RoundTripFidelityTests 等既存）	surfaced
ambiguity	"我記得che-word-mcp有一個大改動"	該大改動實際主體在 ooxml-swift + macdoc（word-aligned-state-sync change）；che-word-mcp 是下游消費者，attribution 需注意	surfaced
missing-context	"確保word修改不會有差"	「不會有差」的 diff 判準未指定：byte-identical / normalizedFingerprint 等價（spec 現行判準）/ 語意等價 —— 三者嚴格度不同	surfaced

---

Current Status

Phase: verified
Last updated: 2026-08-24 by idd-verify

Key Decisions

• Canonical sidecars use the full DOCX filename; legacy stem sidecars remain read-only fallback.
• Legacy-only sessions migrate on next write without deleting or overwriting old files.
• PR Align Word sidecar naming contract (#127) #149 merged current main without force-push and is now mergeable.

Scope Changes

• Added explicit fresh-vs-legacy scenarios and aligned CLI help after review.

Blocking

• CodeQL on PR Align Word sidecar naming contract (#127) #149 is still running; then human review/merge remains.

Commits

• ba6d976 merge main
• 40f50a7 legacy migration scenario
• 1b3e673 CLI help alignment

[kiki830621]

進度更新（2026-07-05）— Phase 0/1/2 全部完成，39/73 tasks

Phase	狀態	Release
Phase 0 — XmlNode tree 基礎	✅ 10/10	ooxml-swift v0.30.0
Phase 1 — typed views → tree projections	✅ 12/12	v0.31.0–v0.31.5
Phase 2 — Operation log	✅ 17/17	v0.32.0（本次釋出）
Phase 3 — Word-import diff / SyncOrchestrator	○ 0/10	v0.33.0（下一步）
Phase 4 — Script transcoder（.mdocx）	○ 0/8	v0.34.0
Phase 5 — v1.0.0 清理	○ 0/10	v1.0.0

本輪落地（v0.31.5 + v0.32.0）：

• 2.5 tree-backed settings.xml 序列化 — dirty settings 保留全部 children（[bug] settings.xml round-trip loss (~19KB → ~400 bytes) — same skip pattern as #67 ooxml-swift#69 根因：writeSettings 硬編碼 400-byte 模板；順帶發現並修復 trackChanges/evenAndOddHeaders flag 從未落盤）
• 2.6 generic sweep：每個 XML part 進 xmlTrees（customXml/theme/fontTable/webSettings/docProps）+ xmlTreeLoadFailures loud-diagnostic
• 2.7–2.10 保存契約 pin 測試（header VML、mc:AlternateContent、nested rPrChange/pPrChange、w16cid、revision source disambiguation）
• 3.15 setParagraphText(id:_:) 經 op log（Decision 4 end-to-end：op → reducer → tree → typed view 讀回 → save 持久化）+ reducer setText 對 paragraph target 的 schema-invalid 輸出修復
• 3.16 SidecarStore：<stem>.oplog.jsonl + <stem>.snapshot.json（opt-in，docx 零 metadata）
• 測試：ooxml-swift 1105 tests 全綠；che-word-mcp 297 tests 對 v0.32.0 全綠

Checklist bugs 現況：#62/#63/#67 的 untouched-part byte-equal 已由 overlay + tree 覆蓋並有 pin 測試；#69 的 settings 場景已修。四張票的正式驗證與關閉留待各票 issue 流程。

下一步：Phase 3（SyncOrchestrator + Word-import diff）— 全新子系統，含 file watcher 與 Word lock 偵測；其中 task 4.8 需要真實 Word 操作（AppleScript），建議在有人守候的 session 執行。

（tasks.md 同步紀錄：先前 10/73 為 stale — 19 個 task 實際已由姊妹 change ooxml-edit-isomorphism-foundation 的 IDD 流程完成，已逐項對 git history 驗證後補標。）

[kiki830621]

進度更新（2026-07-05 晚）— Phase 3 完成，49/73 tasks，ooxml-swift v0.33.0

Phase 3（Word-import diff / SyncOrchestrator）本日全部落地：

• WordImport.diff：element-identity matching（stable ID → structural fingerprint fallback），rsid 噪音正規化歸零；SetText / InsertParagraphAfter+Before / RemoveParagraph；formatting-only 變化 loud 回報（unrepresentedChanges）不靜默吞
• SyncPolicy（.abortOnConflict 預設 / .swiftWins / .wordWins / .askUser）+ ConflictReport + SyncError
• DocxChangeDetector（mtime fast-path + SHA-256；touch-only 不觸發）+ WordLock（~$ owner-file，含 minus-2 命名變體）
• SyncOrchestrator：bootstrapFromDocx（fresh / existing / stale-snapshot 補 import）、importFromDisk（diff → policy → append source: word → materialize → resync）、flush（lock 拒寫 + sidecars + 自寫不自觸發）

🎯 里程碑：真實 Microsoft Word round-trip 整測通過 —— osascript 驅動 Word 16.110.2 實際開檔、改段落、存檔；orchestrator 偵測變更、diff 出 SetText("edited by live Word")、以 source: word 進 op log。「用 round-trip 測試確保 Word 修改不會有差」從這一刻起是可執行的驗證，不是願景。（測試 gated RUN_WORD_INTEGRATION=1，CI 上自動 skip。）

測試：ooxml-swift 1132 tests, 0 failures（+27 本輪）；che-word-mcp 297 tests 對 v0.33.0 全綠。

剩餘：Phase 4（.mdocx script transcoder，8 tasks，v0.34.0 — 即你要的 Swift 腳本驗證面）、Phase 5（v1.0.0 清理，10 tasks）、跨階段 6-AI verify（6 tasks）。

[kiki830621]

進度更新（2026-07-05 深夜）— taxonomy 整合落地，53/77，Phase 4 解除封鎖

• spec 整合：operation taxonomy 收斂到 ooxml-operation-log 單一 home，命名與官方 OOXML（ECMA-376）對齊 #128 spec 整合已 merge（PR spec: consolidate operation taxonomy — single normative home + OOXML-mirror naming #129，squash）：op taxonomy 單一 normative home（ooxml-operation-log）+ OOXML-mirror（ECMA-376）命名；三份 spec 的三版本衝突消除
• ooxml-swift v0.33.1（§4b 實作端，additive）：Operation enum 24 → 32 cases（appendParagraph(in:) / setRuns / defineStyle / beginComponent+endComponent / 三個 run-scoped inline atoms）、payload 擴充（paraId ↔ w14:paraId 管道、RunPayload 格式欄位）、JSONL codec + reducer 全接線；1143 tests 全綠、che-word-mcp 297 tests 對 v0.33.1 全綠
• tasks.md：49/77 → 53/77

下一步：Phase 4（tasks 5.1–5.8）—— .mdocx script transcoder（WordDSLSwift result builders + ScriptExporter/Importer + 15 fixture corpus 驗證），現在有了統一的 canonical op 詞彙可以動工。建議 fresh session 全力做（全新大模組）。

（#128 已 verify-gated PASS + PR merged，等 /idd-close。）